Analytics API
The Analytics API lets you read playback metrics for your workspace. All endpoints are read-only GET requests under /api/analytics/*.
Your API key must have the analytics.read permission. Video read alone is not enough. See Authentication.
Endpoints
| Endpoint | Path |
|---|---|
| Plays | GET /api/analytics/plays |
| Sources | GET /api/analytics/sources |
| Content | GET /api/analytics/content |
| Breakdown | GET /api/analytics/breakdown |
| Completion | GET /api/analytics/completion |
| Watching | GET /api/analytics/watching |
| Engagement | GET /api/analytics/engagement |
| Live | GET /api/analytics/live |
Authentication
Pass your API key as a Bearer token:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://app.ignitevideo.cloud/api/analytics/plays?interval=day"The workspace is taken from the API key. Do not send a workspaceId query parameter.
Category scope
If your API key is limited to specific categories:
- Workspace-wide analytics calls (no video
contentId) still return full-workspace aggregates. - Per-video calls that pass a VOD
contentIdonly succeed when that video is inside the key’s category scope. - Live content (
contentType=live) is not filtered by category scope.
Common query parameters
Many endpoints share these parameters:
| Parameter | Type | Description |
|---|---|---|
contentType | string | vod (default) or live |
contentId | string | Video id or live event id |
from | string | ISO 8601 start time. Defaults to about 30 days ago. |
to | string | ISO 8601 end time. Defaults to now. |
minimumWatchSeconds | number | Minimum watch time for a view to count. Default is 3. |
interval | string | For plays: hour or day (default day) |
limit | number | Max rows for ranked lists. Default is 100. |
Ranges wider than about one year are clamped to the most recent year.
Errors
| Status | Body | Meaning |
|---|---|---|
400 | { "error": "..." } | Invalid query parameters |
403 | — | Missing analytics.read, disabled key, or out-of-scope VOD contentId |
500 | { "error": "analytics_not_configured" } | Analytics is not configured on the server |
502 | { "error": "analytics_upstream_error" } | Upstream analytics error |
504 | { "error": "analytics_timeout" } | Upstream analytics timeout |
Responses include Cache-Control: private, no-store. Do not cache analytics responses in the browser across workspace switches.