Analytics API
L’API Analytics te permet de lire les métriques de lecture et de livraison de ton espace de travail. Tous les endpoints sont des requêtes GET en lecture seule sous /api/analytics/*.
Ta Clé API doit avoir la permission analytics.read. La permission read sur les vidéos ne suffit pas. Voir Authentification.
Endpoints
Les métriques de lecture viennent du player. Les métriques de livraison viennent du CDN et du stockage.
| Endpoint | Path |
|---|---|
| Lectures | GET /api/analytics/views |
| Sources | GET /api/analytics/sources |
| Contenu | GET /api/analytics/content |
| Répartition | GET /api/analytics/breakdown |
| Achèvement | GET /api/analytics/completion |
| Spectateurs | GET /api/analytics/watching |
| Engagement | GET /api/analytics/engagement |
| En direct | GET /api/analytics/live |
| Trafic | GET /api/analytics/traffic |
| Requêtes | GET /api/analytics/requests[/:videoId] |
Authentification
Passe ta Clé API comme Jeton Bearer :
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://app.ignitevideo.cloud/api/analytics/views?interval=day"L’espace de travail est pris depuis la Clé API. N’envoie pas de paramètre de requête workspaceId.
Périmètre de catégories
Si ta Clé API est limitée à certaines catégories :
- Les appels Analytics à l’échelle de l’espace de travail (sans
contentIdvidéo ni:videoId) renvoient toujours des agrégats pour tout l’espace de travail. - Les appels par vidéo qui passent un
contentIdVOD ou:videoIdne réussissent que si cette vidéo est dans le périmètre de catégories de la clé. - Le contenu live (
contentType=live) n’est pas filtré par le périmètre de catégories.
Paramètres de requête communs
Beaucoup d’endpoints partagent ces paramètres :
| Paramètre | Type | Description |
|---|---|---|
contentType | string | vod (par défaut) ou live |
contentId | string | Id vidéo ou id d’événement live |
from | string | Heure de début ISO 8601. Par défaut environ 30 jours en arrière. |
to | string | Heure de fin ISO 8601. Par défaut maintenant. |
minimumWatchSeconds | number | Temps de visionnage minimum pour qu’une vue compte. Par défaut 3. |
interval | string | Pour plays : hour ou day (par défaut day) |
limit | number | Nombre max de lignes pour les listes classées. Par défaut 100. |
Trafic et Requêtes utilisent startDate et endDate à la place de from et to. Les deux sont requis.
Les plages plus larges qu’environ un an sont limitées à l’année la plus récente sur les endpoints de lecture.
Erreurs
| Status | Body | Signification |
|---|---|---|
400 | { "error": "..." } ou texte brut | Paramètres de requête invalides |
403 | — | analytics.read manquant, clé désactivée ou contentId VOD hors périmètre |
500 | { "error": "analytics_not_configured" } | Analytics n’est pas configuré sur le serveur |
502 | { "error": "analytics_upstream_error" } | Erreur Analytics en amont |
504 | { "error": "analytics_timeout" } | Timeout Analytics en amont |
500 / 502 / 504 s’appliquent aux endpoints de lecture. Trafic et requêtes renvoient 400 en texte brut quand startDate ou endDate est manquant ou invalide.
Les réponses de lecture incluent Cache-Control: private, no-store. Ne cache pas les réponses Analytics dans le navigateur lors des changements d’espace de travail.