> 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/documentation/es/dashboard/dashboard-api.md).

# API del panel

Acceso programático a los usuarios de productos de Oxylabs para hacer seguimiento de las estadísticas de uso con la Dashboard API.

El **API del panel** te permite **acceder a las estadísticas de uso de tu producto** de forma programática e integrar las métricas en tus sistemas internos. Esto permite informes automatizados y supervisión del uso en tiempo real sin usar el panel web de Oxylabs.

{% hint style="info" %}
**Nota:** Dashboard API actualmente admite **Datacenter Proxies (DC**) y **Agent Browser (HB)**. También puedes consultar [**Residential Proxies**](https://developers.oxylabs.io/products/es/proxies/residential-proxies/public-api.md), [**Mobile Proxies**](https://developers.oxylabs.io/products/es/proxies/mobile-proxies/public-api.md), [**Web Unblocker**](https://developers.oxylabs.io/products/es/web-unblocker/usage-statistics.md), y [**Web Scraper API**](https://developers.oxylabs.io/products/es/web-scraper-api/usage-and-billing/usage-statistics.md) las estadísticas de uso con solicitudes API sencillas.
{% endhint %}

Todas las solicitudes API pasan por esta ruta base:

```
https://api.oxylabs.io/
```

## Autenticación

{% hint style="warning" %}
**Importante:** Para obtener tu clave de Dashboard API, ponte en contacto con nuestro [**Atención al cliente**](mailto:support@oxylabs.io) equipo. Una vez solicitada, la clave se generará y se te entregará directamente en un día laborable.
{% endhint %}

Debes incluir la clave en el `Authorization` encabezado de cada solicitud usando el `Bearer` esquema.

```
Authorization: Bearer {YOUR_API_KEY}
```

## Endpoints

Dashboard API incluye endpoints para Instance Discovery y Usage Statistics. Todas las respuestas se entregan en formato JSON.

<table><thead><tr><th width="236.8125">Endpoint</th><th>Descripción</th></tr></thead><tbody><tr><td><a href="#instance-discovery">Descubrimiento de instancias</a></td><td>La solicitud devuelve una lista paginada de instancias de producto a las que tu cuenta está autorizada a acceder. Puedes usar los IDs devueltos para filtrar resultados al llamar a otros endpoints.</td></tr><tr><td><a href="#usage-statistics">Estadísticas de uso</a></td><td>La solicitud devuelve estadísticas de uso agregadas por producto para las instancias de producto del cliente autenticado.</td></tr></tbody></table>

### Descubrimiento de instancias

```
GET /stats/v1/filters/instances
```

#### Parámetros de consulta

<table><thead><tr><th width="166">Parámetro</th><th width="268.0481770833333">Descripción</th><th>Tipo</th></tr></thead><tbody><tr><td><code>products[]</code></td><td>Filtra por producto. Valores aceptados: <code>HB</code> (Agent Browser), <code>DC</code> (Datacenter Proxies), <code>null</code> (todos los productos).</td><td>Matriz de cadenas</td></tr><tr><td><code>page</code></td><td>Número de página. Valor predeterminado: <code>1</code>.</td><td>Entero</td></tr><tr><td><code>per_page</code></td><td>Resultados por página. Valor predeterminado: <code>100</code>. Máximo: <code>100</code>.</td><td>Entero</td></tr></tbody></table>

#### Ejemplo de solicitud

Para empezar a filtrar datos, primero debes identificar tus recursos específicos. El siguiente ejemplo muestra cómo listar tus instancias disponibles de Datacenter Proxies (DC) y Agent Browser (HB).

**Ejemplo de entrada**

```
GET /stats/v1/filters/instances?products[]=HB&products[]=DC&page=1&per_page=50
Authorization: Bearer {YOUR_API_KEY}
```

**Ejemplo de salida**

```json
{
  "data": [
    {
      "uuid": "my-hb-instance-uuid",
      "name": "my-hb-instance",
      "status": "enabled",
      "product": "HB"
    },
    {
      "uuid": "my-dc-instance-uuid",
      "name": "my-dc-instance",
      "status": "disabled",
      "product": "DC"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total_items": 2,
      "total_pages": 1
    }
  }
}
```

#### Campos de respuesta

<table><thead><tr><th width="166">Campo</th><th width="268.0481770833333">Descripción</th><th>Tipo</th></tr></thead><tbody><tr><td><code>uuid</code></td><td>Identificador único de la instancia.</td><td>Cadena (UUID)</td></tr><tr><td><code>name</code></td><td>Nombre de la instancia según la configuración del panel.</td><td>Cadena</td></tr><tr><td><code>status</code></td><td>Estado de la instancia del producto (p. ej., <code>habilitado</code> o <code>deshabilitado</code>).</td><td>Cadena</td></tr><tr><td><code>product</code></td><td>Identificador del producto (p. ej., <code>HB</code> (Agent Browser), <code>DC</code> (Datacenter Proxies), etc.).</td><td>Cadena</td></tr><tr><td><code>page</code></td><td>Número de página actual.</td><td>Entero</td></tr><tr><td><code>per_page</code></td><td>Número de resultados en esta página.</td><td>Entero</td></tr><tr><td><code>total_items</code></td><td>Total de registros coincidentes en todas las páginas.</td><td>Entero</td></tr><tr><td><code>total_pages</code></td><td>Número total de páginas. Siempre al menos <code>1</code>, incluso cuando no hay resultados.</td><td>Entero</td></tr></tbody></table>

### Estadísticas de uso

```
GET /stats/v1/usage
```

{% hint style="warning" %}
**Importante:** El rango máximo de fechas para una sola solicitud (la diferencia entre `date_to` y `date_from`) es **31 días**. Para recuperar datos de uso durante un período más largo, realiza tus consultas en lotes de 31 días.
{% endhint %}

#### Parámetros de consulta

<table><thead><tr><th width="166">Parámetro</th><th width="268.0481770833333">Descripción</th><th>Tipo</th></tr></thead><tbody><tr><td><mark style="background-color:green;"><code>product</code></mark></td><td>Identificador del producto (p. ej., <code>HB</code> (Agent Browser), <code>DC</code> (Datacenter Proxies), etc.)</td><td>Cadena</td></tr><tr><td><mark style="background-color:green;"><code>date_to</code></mark></td><td>Fecha de inicio, inclusive (p. ej., UTC <code>YYYY-MM-DDTHH:mm:ssZ</code> o con desplazamiento horario <code>YYYY-MM-DDTHH:mm:ss+02:00</code>).</td><td>Fecha (ISO 8601)</td></tr><tr><td><mark style="background-color:green;"><code>date_from</code></mark></td><td>Fecha de fin, inclusive. Mismo formato que <code>date_to</code>.</td><td>Fecha (ISO 8601)</td></tr><tr><td><mark style="background-color:green;"><code>group_by</code></mark></td><td>Opciones de agrupación de resultados. Valores aceptados: <code>DAY</code>, <code>TARGET</code>, <code>INSTANCE</code>. Se pueden combinar varios valores. El orden de los valores determina el orden de la agrupación de datos.</td><td>Matriz de cadenas</td></tr><tr><td><code>instances[]</code></td><td>Filtra los resultados a instancias específicas. Acepta varios UUID obtenidos de <code>GET /stats/v1/filters/instances</code>. Los UUID no válidos o no reconocidos se ignoran.</td><td>UUID (Matriz de cadenas)</td></tr><tr><td><code>page</code></td><td>Número de página. Valor predeterminado: <code>1</code>.</td><td>Entero</td></tr><tr><td><code>per_page</code></td><td>Resultados por página. Valor predeterminado: <code>100</code>. Máximo: <code>100</code>.</td><td>Entero</td></tr></tbody></table>

\- parámetro obligatorio

#### Ejemplos de solicitudes

**1. Agrupar por TARGET**

El siguiente ejemplo muestra cómo recuperar métricas de uso para Agent Browser (`HB`) agrupando los resultados por target, para ver el recuento total de solicitudes y el volumen de tráfico de cada target dentro del rango de fechas seleccionado.

**Ejemplo de entrada**

```
GET /stats/v1/usage?product=HB&date_from=2025-11-01T00:00:00Z&date_to=2025-11-30T23:59:59Z&group_by[]=TARGET
Authorization: Bearer {YOUR_API_KEY}
```

**Ejemplo de salida**

```json
{
  "data": [
    {"grouped_by": ["some.target.A"], "requests": 10, "traffic_bytes": 100},
    {"grouped_by": ["some.target.B"], "requests": 10, "traffic_bytes": 100}
  ],
  "totals": {
    "requests": 20,
    "traffic_bytes": 200
  },
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total_items": 100,
      "total_pages": 2
    },
    "grouping": ["TARGET"]
  }
```

**2. Agrupar por DAY + TARGET**

Este ejemplo muestra cómo desglosar el uso de Agent Browser (`HB`) por `Día` y `Destino` para ver exactamente cuánto tráfico consumió cada target día a día.

**Ejemplo de entrada**

```
GET /stats/v1/usage?product=HB&date_from=2025-11-01T00:00:00Z&date_to=2025-11-30T23:59:59Z&group_by[]=DAY&group_by[]=TARGET
Authorization: Bearer {YOUR_API_KEY}
```

**Ejemplo de salida**

```json

  "data": [
    {"grouped_by": ["2025-11-01", "some.target.A"], "requests": 10, "traffic_bytes": 100},
    {"grouped_by": ["2025-11-01", "some.target.B"], "requests": 10, "traffic_bytes": 100},
    {"grouped_by": ["2025-11-02", "some.target.A"], "requests": 10, "traffic_bytes": 100},
    {"grouped_by": ["2025-11-02", "some.target.B"], "requests": 10, "traffic_bytes": 100}
  ],
  "totals": {
    "requests": 40,
    "traffic_bytes": 400
  },
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total_items": 200,
      "total_pages": 4
    },
    "grouping": ["DAY", "TARGET"]
  }
}
```

#### Campos de respuesta

<table><thead><tr><th width="190">Campo</th><th width="344.0481770833333">Descripción</th><th>Tipo</th></tr></thead><tbody><tr><td><code>grouped_by</code></td><td>Opciones de agrupación en el mismo orden que los solicitados <code>group_by</code> parámetros.</td><td>Matriz de cadenas</td></tr><tr><td><code>data.requests</code></td><td>Recuento total de solicitudes para la combinación de período/dimensión agrupada.</td><td>Entero</td></tr><tr><td><code>data.traffic_bytes</code></td><td>Tráfico total en bytes para la combinación de período/dimensión agrupada.</td><td>Entero</td></tr><tr><td><code>totals</code></td><td>Valores agregados totales para el período seleccionado.</td><td>Objeto</td></tr><tr><td><code>totals.requests</code></td><td>Recuento total de solicitudes en todo el período seleccionado.</td><td>Entero</td></tr><tr><td><code>totals.traffic_bytes</code></td><td>Tráfico total en bytes en todo el período seleccionado.</td><td>Entero</td></tr><tr><td><code>page</code></td><td>Número de página actual.</td><td>Entero</td></tr><tr><td><code>per_page</code></td><td>Número de resultados en esta página.</td><td>Entero</td></tr><tr><td><code>total_items</code></td><td>Total de registros coincidentes en todas las páginas.</td><td>Entero</td></tr><tr><td><code>total_pages</code></td><td>Número total de páginas. Siempre al menos <code>1</code>, incluso cuando no hay resultados.</td><td>Entero</td></tr><tr><td><code>meta.grouping</code></td><td>Las opciones de agrupación activas en el orden en que aparecen en <code>grouped_by</code>. Refleja el <code>group_by</code> parámetro de solicitud.</td><td>Matriz de cadenas</td></tr></tbody></table>

## Límites de tasa

Para garantizar la estabilidad, los límites de tasa de Dashboard API se aplican por clave API y por cuenta de cliente para todas las solicitudes.

* `10` solicitudes por clave API
* `100` solicitudes en todas las claves API de un cliente individual

## Gestión de errores

Estos son algunos tipos de error comunes que puedes obtener al usar Dashboard API:

<table><thead><tr><th width="166">Código de error</th><th width="268.0481770833333">Mensaje de error</th><th>Descripción</th></tr></thead><tbody><tr><td><code>400</code></td><td>Solicitud incorrecta</td><td>No se pudo entender la solicitud. Comprueba si la solicitud está formateada correctamente.</td></tr><tr><td><code>401</code></td><td>Solicitud no válida</td><td>El usuario ha introducido una clave API no válida.</td></tr><tr><td><code>403</code></td><td>Prohibido</td><td>Acceso denegado: falta la clave API. Ponte en contacto con soporte o con tu administrador de cuenta.</td></tr><tr><td><code>429</code></td><td>Demasiadas solicitudes</td><td>El usuario ha alcanzado el límite de hilos/sesiones simultáneas.</td></tr><tr><td><code>500</code></td><td>Error interno del servidor</td><td>Se produjo un problema inesperado con el servidor. Inténtalo de nuevo más tarde.</td></tr></tbody></table>

Para preguntas, problemas de acceso o soporte de integración, ponte en contacto con [**support@oxylabs.io**](mailto:support@oxylabs.io) o con tu administrador de cuenta. Al informar de un problema, incluye:

* El endpoint y los parámetros de consulta utilizados
* El código de estado HTTP devuelto
* El cuerpo completo de la respuesta (censura tu clave API antes de compartirla)
* Marcas de tiempo de las solicitudes fallidas (se prefiere UTC)


---

# 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/documentation/es/dashboard/dashboard-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.
