# API del dashboard

El **Dashboard API** le permite **acceder a las estadísticas de uso de su producto** de forma programática e integrar las métricas en sus sistemas internos. Esto permite generar informes automáticos y monitorizar el uso en tiempo real sin usar el panel de Oxylabs en la web.

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

Todas las solicitudes API pasan por esta ruta base:

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

## Autenticación

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

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

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

## Puntos finales

Dashboard API incluye puntos finales para Descubrimiento de instancias de producto y Estadísticas de uso. Todas las respuestas se entregan en formato JSON. 

<table><thead><tr><th width="236.8125">Punto final</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 su cuenta está autorizada a acceder. Puede usar los IDs devueltos para filtrar resultados al llamar a otros puntos finales.</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>Filtrar por producto. Valores aceptados: <code>HB</code> (Headless Browser), <code>DC</code> (Datacenter Proxies), <code>null</code> (todos los productos).</td><td>Array de cadenas</td></tr><tr><td><code>page</code></td><td>Número de página. Predeterminado: <code>1</code>.</td><td>Entero</td></tr><tr><td><code>per_page</code></td><td>Resultados por página. Predeterminado: <code>100</code>. Máximo: <code>100</code>.</td><td>Entero</td></tr></tbody></table>

#### Ejemplo de solicitud

Para comenzar a filtrar datos, primero necesita identificar sus recursos específicos. El siguiente ejemplo muestra cómo listar sus instancias disponibles de Datacenter Proxies (DC) y Headless 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**&#x20;

```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 tal como está 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>enabled</code> o <code>disabled</code>).</td><td>Cadena</td></tr><tr><td><code>product</code></td><td>Identificador del producto (p. ej., <code>HB</code> (Headless 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 de fechas máximo para una sola solicitud (la diferencia entre `date_to` y `date_from`) es **31 days**. Para obtener datos de uso de un período más largo, realice sus consultas en bloques 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> (Headless 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 zona horaria explícita <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>Array de cadenas</td></tr><tr><td><code>instances[]</code></td><td>Filtra los resultados a instancias específicas. Acepta múltiples 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. Predeterminado: <code>1</code>.</td><td>Entero</td></tr><tr><td><code>per_page</code></td><td>Resultados por página. Predeterminado: <code>100</code>. Máximo: <code>100</code>.</td><td>Entero</td></tr></tbody></table>

&#x20;     \- parámetro obligatorio

#### Ejemplos de solicitud

**1. Agrupar por TARGET**

El siguiente ejemplo muestra cómo recuperar métricas de uso de Headless 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**&#x20;

```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 Headless Browser (`HB`) por `Día` y `Target` 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**&#x20;

```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>Array 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>Array de cadenas</td></tr></tbody></table>

## Límites de velocidad

Para garantizar la estabilidad, los límites de velocidad 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

## Manejo de errores

Estos son algunos tipos de error comunes que puede recibir 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. Compruebe 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 API no válida.</td></tr><tr><td><code>403</code></td><td>Prohibido</td><td>Acceso denegado: falta la clave API. Póngase en contacto con soporte o con su 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éntelo de nuevo más tarde.</td></tr></tbody></table>

Si tiene preguntas, problemas de acceso o necesita ayuda con la integración, póngase en contacto con [**support@oxylabs.io**](mailto:support@oxylabs.io) o con su gestor de cuenta. Al informar de un problema, incluya:

* El punto final y los parámetros de consulta utilizados
* El código de estado HTTP devuelto
* El cuerpo completo de la respuesta (censure su clave API antes de compartirlo)
* Marcas de tiempo de las solicitudes fallidas (se prefiere UTC)


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.oxylabs.io/documentation/es/dashboard/dashboard-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.