Analytics API
The Analytics API lets you read playback and delivery 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
Playback metrics come from the player. Delivery metrics come from CDN and storage.
| Endpoint | Path |
|---|---|
| Plays | GET /api/analytics/views |
| 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 |
| Traffic | GET /api/analytics/traffic |
| Requests | GET /api/analytics/requests[/:videoId] |
Authentication
Pass your API key as a Bearer token:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://app.ignitevideo.cloud/api/analytics/views?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
contentIdor:videoId) still return full-workspace aggregates. - Per-video calls that pass a VOD
contentIdor:videoIdonly 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. |
Traffic and Requests use startDate and endDate instead of from and to. Both are required.
Ranges wider than about one year are clamped to the most recent year on playback endpoints.
Errors
| Status | Body | Meaning |
|---|---|---|
400 | { "error": "..." } or plain text | 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 |
500 / 502 / 504 apply to playback endpoints. Traffic and requests return 400 as plain text when startDate or endDate is missing or invalid.
Playback responses include Cache-Control: private, no-store. Do not cache analytics responses in the browser across workspace switches.