Primeros pasos

La API de Analytics de VTurb te da acceso programático a los datos de analytics de tu cuenta de VTurb, para que puedas:

• Consultar datos en tiempo real e históricos
• Crear tus propios informes y gráficos
• Llevar los datos de analytics a tus aplicaciones
• Automatizar pipelines de datos y decisiones de negocio

Cómo empezar

1. Crea una cuenta, si todavía no tienes una.
2. Genera una API key en tu panel.
3. Envíala en cada solicitud, junto con la versión de la API y un User-Agent, como se describe en Autenticación.
4. Elige los datos que necesitas entre los endpoints listados en el menú lateral.

URL base

https://analytics.vturb.com

Las solicitudes y las respuestas son JSON. Las consultas son solicitudes POST con un cuerpo JSON; algunas búsquedas, como GET /players/list y GET /quota/usage, son GET.

Fechas y zonas horarias

Salvo que el endpoint indique otra cosa, las fechas se envían con el formato YYYY-MM-DD HH:MM:SS y se leen en la zona horaria indicada en timezone, un nombre IANA como America/Sao_Paulo. Sin timezone, las fechas se leen en UTC.

{
  "start_date": "2026-09-01 00:00:00",
  "timezone": "America/Sao_Paulo"
}

Cada consulta solo ve los reproductores y los datos de la empresa a la que pertenece tu API key.

Respuestas

• Un parámetro ausente o inválido recibe 400, con un error que indica cuál.
• En la mayoría de las consultas, un player_id que no es de tu cuenta recibe 200 con ceros o una lista vacía, no un error. Si todos los números vuelven en cero, comprueba el ID con GET /players/list. /headlines/stats_by_player, /turbo/stats_by_player y /smart_autoplays/stats_by_player responden 400 en ese caso.
• Los resultados se guardan en caché y se actualizan en segundo plano, así que la actividad de los últimos minutos puede no aparecer todavía.

Límites

Tu empresa tiene una cuota de consultas por ventana de tiempo, definida por tu plan y compartida por todas sus API keys:

GET /quota/usage devuelve los límites de tu empresa y cuánto de cada uno ya se usó. Una sola solicitud puede contar como más de una consulta.

Cuando la cuota se agota, la API responde 429 Too Many Requests, con details indicando qué límite se alcanzó y cuándo se renueva:

{
  "error": "Query quota exceeded for this API key. Please retry in a few moments or contact support at [email protected] if this persists.",
  "code": 201,
  "details": {
    "limit_kind": "queries",
    "used": 60,
    "limit": 60,
    "remaining": 0,
    "interval_seconds": 60,
    "resets_at": "2026-04-27T12:35:00Z"
  }
}

limit_kind es el límite que se agotó, como queries o read_bytes, los datos que leen las consultas. Espera hasta resets_at antes de reintentar, o un momento si details no viene. Si tu integración necesita un límite mayor, contacta con soporte.

Soporte

Los ejemplos de código de cada endpoint están en su página. Para cualquier otra duda, contacta con nuestro soporte en help.vturb.com.