> 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 dashboard

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

La **API de Dashboard** te permite **acceder a tus estadísticas de uso del producto** programáticamente 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:** La API de Dashboard actualmente admite **Datacenter Proxies (DC**) y **Agent Browser (HB)**. También puedes rastrear [**Residential Proxies**](/products/es/proxies/residential-proxies/public-api.md), [**Mobile Proxies**](/products/es/proxies/mobile-proxies/public-api.md), [**Web Unblocker**](/products/es/web-unblocker/usage-statistics.md), y [**Web Scraper API**](/products/es/web-scraper-api/usage-and-billing/usage-statistics.md) estadísticas de uso con simples solicitudes de API.
{% endhint %}

Todas las solicitudes de API pasan por esta ruta base:

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

## Autenticación

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

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

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

## Puntos finales

La API de Dashboard incluye endpoints para Descubrimiento de instancias del producto y Estadísticas de uso. 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 del 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>Arreglo 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 necesitas 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 configurado en el 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, inclusiva (p. ej., UTC <code>YYYY-MM-DDTHH:mm:ssZ</code> o con zona horaria <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, inclusiva. 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>Arreglo 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 inválidos o no reconocidos se ignoran.</td><td>UUID (Array 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 solicitud

**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 para 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 ambos `Día` y `objetivo` 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 <code>group_by</code> parámetros solicitados.</td><td>Arreglo 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 totales agregados 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>Arreglo de cadenas</td></tr></tbody></table>

## Límites de velocidad

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

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

## Manejo de errores

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

<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. Verifica si la solicitud está formateada correctamente.</td></tr><tr><td><code>401</code></td><td>Solicitud inválida</td><td>El usuario ha introducido una clave de API inválida.</td></tr><tr><td><code>403</code></td><td>Prohibido</td><td>Acceso denegado: falta la clave de API. Ponte en contacto con soporte o con tu gestor 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 concurrentes.</td></tr><tr><td><code>500</code></td><td>Error interno del servidor</td><td>Tuvimos 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 gestor 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 (oculta tu clave de 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.