API del dashboard

Acceso programático a los usuarios de Proxies de Oxylabs para hacer seguimiento de las estadísticas de uso con la 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.

Nota: Dashboard API actualmente admite Datacenter Proxies (DC) y Headless Browser (HB). También puede consultar las estadísticas de uso de Residential Proxies, Mobile Proxies, Web Unblocker, y Web Scraper API con simples solicitudes API.

Todas las solicitudes API pasan por esta ruta base:

https://api.oxylabs.io/

Autenticación

Importante: Para obtener su clave de Dashboard API, póngase en contacto con nuestro equipo de Atención al cliente . Una vez solicitada, la clave se generará y se le entregará directamente en el plazo de un día hábil.

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.

Punto final	Descripción
Descubrimiento de instancias	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.
Estadísticas de uso	La solicitud devuelve estadísticas de uso agregadas por producto para las instancias de producto del cliente autenticado.

Descubrimiento de instancias

GET /stats/v1/filters/instances

Parámetros de consulta

Parámetro	Descripción	Tipo
products[]	Filtrar por producto. Valores aceptados: HB (Headless Browser), DC (Datacenter Proxies), null (todos los productos).	Array de cadenas
page	Número de página. Predeterminado: 1.	Entero
per_page	Resultados por página. Predeterminado: 100. Máximo: 100.	Entero

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

{
  "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

Campo	Descripción	Tipo
uuid	Identificador único de la instancia.	Cadena (UUID)
name	Nombre de la instancia tal como está configurado en el panel.	Cadena
status	Estado de la instancia del producto (p. ej., enabled o disabled).	Cadena
product	Identificador del producto (p. ej., HB (Headless Browser), DC (Datacenter Proxies), etc.).	Cadena
page	Número de página actual.	Entero
per_page	Número de resultados en esta página.	Entero
total_items	Total de registros coincidentes en todas las páginas.	Entero
total_pages	Número total de páginas. Siempre al menos 1, incluso cuando no hay resultados.	Entero

Estadísticas de uso

GET /stats/v1/usage

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.

Parámetros de consulta

Parámetro	Descripción	Tipo
product	Identificador del producto (p. ej., HB (Headless Browser), DC (Datacenter Proxies), etc.)	Cadena
date_to	Fecha de inicio, inclusive (p. ej., UTC YYYY-MM-DDTHH:mm:ssZ o con zona horaria explícita YYYY-MM-DDTHH:mm:ss+02:00).	Fecha (ISO 8601)
date_from	Fecha de fin, inclusive. Mismo formato que date_to.	Fecha (ISO 8601)
group_by	Opciones de agrupación de resultados. Valores aceptados: DAY, TARGET, INSTANCE. Se pueden combinar varios valores. El orden de los valores determina el orden de la agrupación de datos.	Array de cadenas
instances[]	Filtra los resultados a instancias específicas. Acepta múltiples UUID obtenidos de GET /stats/v1/filters/instances. Los UUID inválidos o no reconocidos se ignoran.	UUID (Array de cadenas)
page	Número de página. Predeterminado: 1.	Entero
per_page	Resultados por página. Predeterminado: 100. Máximo: 100.	Entero

- 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

{
  "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

  "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

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

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:

Código de error	Mensaje de error	Descripción
400	Solicitud incorrecta	No se pudo entender la solicitud. Compruebe si la solicitud está formateada correctamente.
401	Solicitud inválida	El usuario ha introducido una clave API no válida.
403	Prohibido	Acceso denegado: falta la clave API. Póngase en contacto con soporte o con su gestor de cuenta.
429	Demasiadas solicitudes	El usuario ha alcanzado el límite de hilos/sesiones concurrentes.
500	Error interno del servidor	Tuvimos un problema inesperado con el servidor. Inténtelo de nuevo más tarde.

Si tiene preguntas, problemas de acceso o necesita ayuda con la integración, póngase en contacto con [e-mail] 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)