Analytics API

La API de Analytics te permite leer métricas de reproducción y de entrega de tu espacio de trabajo. Todos los endpoints son solicitudes GET de solo lectura bajo /api/analytics/*.

Tu Clave API debe tener el permiso analytics.read. Solo read de vídeos no es suficiente. Consulta Autenticación.

Endpoints

Las métricas de reproducción vienen del player. Las métricas de entrega vienen del CDN y del almacenamiento.

Endpoint	Path
Reproducciones	`GET /api/analytics/views`
Fuentes	`GET /api/analytics/sources`
Contenido	`GET /api/analytics/content`
Desglose	`GET /api/analytics/breakdown`
Conclusión	`GET /api/analytics/completion`
Espectadores	`GET /api/analytics/watching`
Engagement	`GET /api/analytics/engagement`
En vivo	`GET /api/analytics/live`
Tráfico	`GET /api/analytics/traffic`
Solicitudes	`GET /api/analytics/requests[/:videoId]`

Autenticación

Pasa tu Clave API como Token Bearer:


curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.ignitevideo.cloud/api/analytics/views?interval=day"

El espacio de trabajo se toma de la Clave API. No envíes un parámetro de consulta workspaceId.

Alcance de categorías

Si tu Clave API está limitada a categorías específicas:

Las llamadas de Analytics a nivel de espacio de trabajo (sin contentId de vídeo ni :videoId) siguen devolviendo agregados de todo el espacio de trabajo.
Las llamadas por vídeo que pasan un contentId VOD o :videoId solo se realizan correctamente cuando ese vídeo está dentro del alcance de categorías de la clave.
El contenido en vivo (contentType=live) no se filtra por el alcance de categorías.

Parámetros de consulta comunes

Muchos endpoints comparten estos parámetros:

Parámetro	Tipo	Descripción
`contentType`	`string`	`vod` (predeterminado) o `live`
`contentId`	`string`	Id de vídeo o id de evento en vivo
`from`	`string`	Hora de inicio ISO 8601. Predeterminado: hace unos 30 días.
`to`	`string`	Hora de fin ISO 8601. Predeterminado: ahora.
`minimumWatchSeconds`	`number`	Tiempo mínimo de visualización para que cuente una vista. Predeterminado: `3`.
`interval`	`string`	Para plays: `hour` o `day` (predeterminado `day`)
`limit`	`number`	Máx. de filas para listas clasificadas. Predeterminado: `100`.

Tráfico y Solicitudes usan startDate y endDate en lugar de from y to. Ambos son obligatorios.

Los rangos de más de aproximadamente un año se limitan al año más reciente en los endpoints de reproducción.

Errores

Status	Body	Significado
`400`	`{ "error": "..." }` o texto plano	Parámetros de consulta no válidos
`403`	—	Falta `analytics.read`, clave deshabilitada o `contentId` VOD fuera de alcance
`500`	`{ "error": "analytics_not_configured" }`	Analytics no está configurado en el servidor
`502`	`{ "error": "analytics_upstream_error" }`	Error de Analytics upstream
`504`	`{ "error": "analytics_timeout" }`	Timeout de Analytics upstream

500 / 502 / 504 se aplican a los endpoints de reproducción. Tráfico y solicitudes devuelven 400 como texto plano cuando falta startDate o endDate o no es válido.

Las respuestas de reproducción incluyen Cache-Control: private, no-store. No almacenes en caché las respuestas de Analytics en el navegador al cambiar de espacio de trabajo.