> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/es/proxies/residential-proxies/public-api.md).

# Public API

Gestiona programáticamente subusuarios de Residential Proxies, establece límites de tráfico y supervisa las estadísticas de uso con la Public API.

La [**Public API**](https://residential-api.oxylabs.io/v2/docs) te permite **gestionar usuarios proxy de forma programática** (a través de una interfaz RESTful `https://residential-api.oxylabs.io/v2`) sin usar el panel. Puedes crear, eliminar y modificar subusuarios proxy, establecer límites de uso del tráfico y ver el uso de tráfico actual e histórico.

### Rutas de API disponibles

Endpoint base:

```
https://residential-api.oxylabs.io/v2
```

<table data-full-width="false"><thead><tr><th width="78.15625">Método</th><th width="406.92578125">Ruta</th><th>Descripción</th></tr></thead><tbody><tr><td><mark style="color:$success;">POST</mark></td><td><code>/login</code></td><td>Autentícate para obtener el token de acceso (JWT).</td></tr><tr><td><mark style="color:azul;">GET</mark></td><td><code>/users/{userId}/sub-users</code></td><td>Recupera todos los subusuarios activos</td></tr><tr><td><mark style="color:$success;">POST</mark></td><td><code>/users/{userId}/sub-users</code></td><td>Crea un nuevo subusuario.</td></tr><tr><td><mark style="color:azul;">GET</mark></td><td><code>/users/{userId}/sub-users/{subUserId}</code></td><td>Recupera las estadísticas de uso del tráfico de un subusuario específico.</td></tr><tr><td><mark style="color:$primary;">PATCH</mark></td><td><code>/users/{userId}/sub-users/{subUserId}</code></td><td>Modifica un subusuario.</td></tr><tr><td><mark style="color:rojo;">DELETE</mark></td><td><code>/users/{userId}/sub-users/{subUserId}</code></td><td>Elimina un subusuario.</td></tr><tr><td><mark style="color:azul;">GET</mark></td><td><code>/users/{userId}/sub-users/{subUserId}/target-stats</code></td><td>Obtén el uso de tráfico del subusuario por dominio de destino (últimos 30 días, requiere una fecha específica).</td></tr><tr><td><mark style="color:azul;">GET</mark></td><td><code>/users/{userId}/client-stats</code></td><td>Recupera el uso total de tráfico del mes actual.</td></tr></tbody></table>

### Flujo de autenticación y uso

Todas las solicitudes de la API (excepto `/login`) requieren un JSON Web Token (JWT) pasado en el `Authorization: Bearer {token}` encabezado HTTP.

{% hint style="info" %}
La `login` el endpoint requiere las credenciales de tu usuario principal (el primer subusuario en la lista de usuarios de tu panel). Si cambiaste recientemente la contraseña de tu usuario principal, usa la contraseña original o [contacta con soporte](mailto:support@oxylabs.io).&#x20;
{% endhint %}

{% hint style="warning" %}
El token de acceso JWT generado expira en 1 hora. Después de expirar, debes solicitar un nuevo token mediante `POST /login`.
{% endhint %}

{% stepper %}
{% step %}

### Generar token de acceso JWT

Autentícate mediante `POST /login` autenticación básica HTTP con las credenciales de tu usuario principal (codificadas en base64).

```bash
curl -X "POST" \
  "https://residential-api.oxylabs.io/v2/login" \
  -H "accept: application/json" \
  -u "MAIN_USERNAME:MAIN_PASSWORD"
```

La respuesta incluye dos valores clave:

```json
{
  "user_id": "00000000-0000-0000-0000-000000000000",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

Guarda el `user_id` y `token` devuelto para todas las solicitudes posteriores.
{% endstep %}

{% step %}

### Realiza solicitudes autenticadas a la API

Incluye el JWT en el `Authorization: Bearer {token}` encabezado y pasa tu `user_id` en la ruta de la solicitud para consultar la API y gestionar usuarios y comprobar estadísticas.

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X "GET" \
  "https://residential-api.oxylabs.io/v2/users/YOUR_USER_ID/client-stats" \
  -H "accept: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

user_id = "00000000-0000-0000-0000-000000000000"
jwt_token = "YOUR_JWT_TOKEN"

url = f"https://residential-api.oxylabs.io/v2/users/{user_id}/client-stats"
headers = {
    "accept": "application/json",
    "Authorization": f"Bearer {jwt_token}"
}

response = requests.get(url, headers=headers)
print(response.json())
```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const axios = require('axios');

const userId = '00000000-0000-0000-0000-000000000000';
const jwtToken = 'YOUR_JWT_TOKEN';

axios.get(`https://residential-api.oxylabs.io/v2/users/${userId}/client-stats`, {
  headers: {
    'accept': 'application/json',
    'Authorization': `Bearer ${jwtToken}`
  }
})
.then(response => console.log(response.data))
.catch(error => console.error(error));
```

{% endtab %}
{% endtabs %}

#### Ejemplo de salida

```json
{
  "traffic": 1.2354839,
  "date_from": "2026-09-01",
  "date_to": "2026-09-14"
}
```

{% endstep %}
{% endstepper %}

### Configuración de entrada Backconnect (CNAME)

Para enrutar el tráfico del proxy a través de tu nombre de dominio personalizado en lugar de `pr.oxylabs.io`, configura un registro DNS `CNAME` en el administrador de tu proveedor DNS.

1. Crea un nuevo `CNAME` registro en tu proveedor DNS (por ejemplo, Cloudflare, Route 53).
2. Establece el nombre de host/subdominio (por ejemplo, `entry.yourdomain.com`) para apuntar a `pr.oxylabs.io`.
3. Usa tu nombre de dominio personalizado en lugar de `pr.oxylabs.io` en todas las cadenas de conexión de solicitudes del proxy.

![Backconnect](https://2786356907-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FBQ7Zf9paoN3FTeGcyfY1%2Fuploads%2Fgit-blob-9d15ff608e52a76e6d288eb45c3bd648ddf970ef%2Fcname.jpg?alt=media)

Para más información, contacta con [**Soporte al cliente**](mailto:support@oxylabs.io) o con tu gestor de cuenta.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.oxylabs.io/products/es/proxies/residential-proxies/public-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.