Aller au contenu

API des analyses

Deux sortes de chiffres vivent ici, et la différence compte.

Les routes en direct appellent Instagram, TikTok, YouTube ou Threads au moment de la demande et parlent de maintenant. Les routes relevées lisent l’historique qu’UseNadia stocke lui-même, toutes les 30 minutes, et parlent d’avant : c’est le seul moyen de comparer une vidéo publiée hier avec une vidéo publiée le mois dernier. Les routes relevées n’existent pas dans upstream.

GET /analytics/{integration} chiffres du compte, en direct
GET /analytics/post/{postId} chiffres d’une publication, en direct
GET /video-list/{integrationId} le catalogue, en direct depuis le fournisseur
GET /analytics-history/{integrationId} la série du compte, relevée
GET /video-history/{integrationId} les séries par vidéo, relevées
GET /analytics/{integration}?date=30
Paramètre Où Obligatoire Description
integration chemin Oui L’id du canal
date requête Oui Nombre de jours en arrière : 7, 30, 90…

Réponse 200, une série par métrique. Les libellés dépendent de la plateforme (abonnés, portée, j’aime, vues…) :

[
{
"label": "Followers",
"data": [
{ "date": "2026-10-19", "total": "1250" },
{ "date": "2026-10-20", "total": "1280" }
],
"percentageChange": 2.4
}
]

total revient sous forme de chaîne, comme les plateformes le renvoient. Un tableau vide signifie que la plateforme n’expose aucune métrique de compte pour ce canal.

GET /analytics/post/{postId}?date=30

Mêmes paramètres, pour une publication parue. La réponse a trois formes :

Réponse Sens
[ { label, data, percentageChange } ] Les métriques, même forme que pour le compte
{ "missing": true } La publication est parue mais la plateforme n’a renvoyé aucun id (releaseId vaut missing) : réparez-la d’abord avec les routes de release id
[] La publication n’est pas encore parue, ou la plateforme n’a pas de métriques par publication
GET /video-list/{integrationId}
Requête Type Description
max_count number Nombre de vidéos
cursor number Curseur du fournisseur pour la page suivante

Les performances par vidéo (vues, j’aime, commentaires, partages), lues en direct chez le fournisseur, là où /analytics/{integration} agrège tout le compte. La forme est celle du fournisseur : TikTok et Instagram diffèrent. 400 quand la plateforme n’a pas de liste par vidéo.

Les deux routes d’historique prennent la même requête. Sans from, la fenêtre couvre les 30 derniers jours ; sans to, elle s’arrête maintenant.

Requête Type Description
from date ISO Début de la fenêtre
to date ISO Fin de la fenêtre
limit entier ≥ 1 Taille de page
offset entier ≥ 0 Pour aller au-delà du plafond du serveur

Une lecture est plafonnée côté serveur à 5 000 lignes. offset permet d’aller au-delà, et total dit quand s’arrêter. Le canal doit être le vôtre : 404 sinon.

GET /analytics-history/{integrationId}
{
"items": [
{ "integrationId": "cm4ean69r0003w8w1cdomox9n", "at": "2026-10-20T09:30:00.000Z", "metric": "followers", "value": 1280 }
],
"total": 1284,
"limit": 5000,
"offset": 0,
"from": "2026-09-20T09:30:00.000Z",
"to": "2026-10-20T09:30:00.000Z"
}

Une ligne par métrique et par passage du relevé, metric nommée comme le fournisseur la nomme.

GET /video-history/{integrationId}

Même requête, plus un paramètre :

Requête Type Description
videoId string Se limiter à une vidéo. Omettez-le pour obtenir les séries de toutes les vidéos en un seul appel

La réponse porte deux champs de plus :

Champ Description
videos L’identité des ID présents dans items : videoId, title, cover, duration. Les séries seules ne connaissent que des ID de vidéo opaques
hidden Combien de vidéos ont été confirmées supprimées chez le fournisseur et laissées hors de items

Les lignes arrivent de la vidéo la plus récente à la plus ancienne : la première page contient toujours les vidéos qui comptent le plus.

Le tableau de contenu lit le même historique pour afficher des chiffres sur ses cartes publiées.