Analytics API
Die Analytics API ermöglicht dir, Playback- und Delivery-Metriken für deinen Workspace abzurufen. Alle Endpoints sind schreibgeschützte GET-Anfragen unter /api/analytics/*.
Dein API-Key braucht die Berechtigung analytics.read. Video-read allein reicht nicht. Siehe Authentifizierung.
Endpoints
Playback-Metriken kommen vom Player. Delivery-Metriken kommen von CDN und Storage.
| Endpoint | Path |
|---|---|
| Wiedergaben | GET /api/analytics/views |
| Quellen | GET /api/analytics/sources |
| Inhalte | GET /api/analytics/content |
| Aufschlüsselung | GET /api/analytics/breakdown |
| Abschluss | GET /api/analytics/completion |
| Zuschauer | GET /api/analytics/watching |
| Engagement | GET /api/analytics/engagement |
| Live | GET /api/analytics/live |
| Traffic | GET /api/analytics/traffic |
| Anfragen | GET /api/analytics/requests[/:videoId] |
Authentifizierung
Übergib deinen API-Key als Bearer-Token:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://app.ignitevideo.cloud/api/analytics/views?interval=day"Der Workspace wird aus dem API-Key abgeleitet. Sende keinen Query-Parameter workspaceId.
Kategorie-Scope
Wenn dein API-Key auf bestimmte Kategorien beschränkt ist:
- Workspace-weite Analytics-Aufrufe (ohne Video-
contentIdoder:videoId) liefern weiterhin Aggregate für den gesamten Workspace. - Pro-Video-Aufrufe mit einer VOD-
contentIdoder:videoIdgelingen nur, wenn das Video im Kategorie-Scope des Keys liegt. - Live-Inhalte (
contentType=live) werden nicht nach Kategorie-Scope gefiltert.
Gemeinsame Query-Parameter
Viele Endpoints teilen diese Parameter:
| Parameter | Typ | Beschreibung |
|---|---|---|
contentType | string | vod (Standard) oder live |
contentId | string | Video-ID oder Live-Event-ID |
from | string | ISO-8601-Startzeit. Standard ca. vor 30 Tagen. |
to | string | ISO-8601-Endzeit. Standard jetzt. |
minimumWatchSeconds | number | Minimale Watch Time, damit ein View zählt. Standard ist 3. |
interval | string | Für Plays: hour oder day (Standard day) |
limit | number | Max. Zeilen für Rankings. Standard ist 100. |
Traffic und Anfragen nutzen startDate und endDate statt from und to. Beide sind erforderlich.
Bereiche größer als etwa ein Jahr werden auf Playback-Endpoints auf das jüngste Jahr begrenzt.
Fehler
| Status | Body | Bedeutung |
|---|---|---|
400 | { "error": "..." } oder Klartext | Ungültige Query-Parameter |
403 | — | Fehlendes analytics.read, deaktivierter Key oder VOD-contentId außerhalb des Scopes |
500 | { "error": "analytics_not_configured" } | Analytics ist auf dem Server nicht konfiguriert |
502 | { "error": "analytics_upstream_error" } | Upstream-Analytics-Fehler |
504 | { "error": "analytics_timeout" } | Upstream-Analytics-Timeout |
500 / 502 / 504 gelten für Playback-Endpoints. Traffic und Anfragen liefern 400 als Klartext, wenn startDate oder endDate fehlt oder ungültig ist.
Playback-Antworten enthalten Cache-Control: private, no-store. Cache Analytics-Antworten nicht im Browser über Workspace-Wechsel hinweg.