Se connecterCommencer l’essai gratuit
easyCoexistence API officielles

Métriques vidéo TikTok via l'API : vues, temps de visionnage et complétion

L'API for Business de TikTok renvoie les métriques cumulées de chaque publication via GET /business/video/list/, demandées par nom dans fields : video_views, reach, likes, comments, shares et favorites, total_time_watched et average_time_watched en secondes, full_video_watched_rate, video_view_retention, impression_sources et répartitions des spectateurs comme audience_countries. La plupart des compteurs arrivent avec 24 à 48 heures de retard et cessent de se mettre à jour 365 jours après la publication.

easyCoexistence lit les métriques d'une vidéo TikTok avec get_social_insights depuis Claude, ChatGPT ou votre propre code : nommez les champs voulus, comme video_views, reach ou full_video_watched_rate, et donnez l'item_id de la vidéo.

video.insights

Périmètre requis pour le temps de visionnage, la complétion, la rétention, les sources de trafic et les répartitions des spectateurs ; les compteurs de base nécessitent video.list.

7 days

Inactivité au-delà de laquelle la portée, le temps de visionnage, les sources de trafic et audience_countries peuvent manquer pour une vidéo.

10

La plupart des entrées des listes audience_countries et audience_cities d'une vidéo.

24 to 48 h

Délai habituel pour video_views, likes, portée, temps de visionnage et sources de trafic, en UTC.

Quelles métriques une vidéo possède-t-elle ?

GET /business/video/list/ renvoie celles-ci pour chaque publication nommée dans fields, agrégées sur toute la durée de vie de la publication et non sur la fenêtre de 60 jours des métriques de compte. Les compteurs comme les vues et les likes nécessitent le scope video.list sur le token, tandis que les chiffres de visionnage, de complétion et de rétention nécessitent video.insights :

video_viewsViews, counted on the first playback in an impression session
reachPeople who watched the post at least once
likes, comments, sharesLifetime totals; shares include sends to friends inside TikTok
favoritesTimes the post was added to favorites
total_time_watchedSeconds viewers spent watching, in total
average_time_watchedAverage seconds viewers spent watching
full_video_watched_rateShare of viewers who finished the video
video_view_retentionShare of viewers still watching at each second
impression_sourcesWhere viewers found the post, by share
new_followersViewers who started following the account
engagement_likesShare of viewers who liked at each second
video_durationLength of the video in seconds

Comment les demander ?

Nommez-les dans fields, un tableau JSON qui doit inclure item_id dès qu'il liste plus d'un champ, et choisissez les publications avec filters.video_ids. Sans ce filtre, l'endpoint parcourt les publications du compte, 20 à la fois :

Metrics for one video
curl -G 'https://business-api.tiktok.com/open_api/v1.3/business/video/list/' \
  -H 'Access-Token: <ACCESS_TOKEN>' \
  --data-urlencode 'business_id=<OPEN_ID>' \
  --data-urlencode 'fields=["item_id","video_views","reach","video_duration","total_time_watched","average_time_watched","full_video_watched_rate","impression_sources","audience_countries"]' \
  --data-urlencode 'filters={"video_ids":["<ITEM_ID>"]}'

À quoi ressemble la réponse ?

Un tableau videos avec un objet par publication et les champs demandés, plus cursor et has_more pour la pagination. L'exemple de TikTok, raccourci, montre les unités : temps de visionnage en secondes avec jusqu'à trois décimales, et full_video_watched_rate sous forme décimale, 0.0237 ici :

A video's metrics, from TikTok's example
{
  "code": 0,
  "message": "OK",
  "request_id": "2021080307532501024502410704A7306F",
  "data": {
    "videos": [
      {
        "item_id": "6990565363377392901",
        "video_views": 1231,
        "reach": 154,
        "likes": 10,
        "comments": 2,
        "shares": 0,
        "video_duration": 20.0,
        "total_time_watched": 695.942,
        "average_time_watched": 4.118,
        "full_video_watched_rate": 0.0237,
        "impression_sources": [
          { "impression_source": "For You", "percentage": 0.8983 },
          { "impression_source": "Personal Profile", "percentage": 0.0904 },
          { "impression_source": "Follow", "percentage": 0.0113 }
        ],
        "audience_countries": [
          { "country": "US", "percentage": 0.7574 },
          { "country": "GB", "percentage": 0.1775 }
        ]
      }
    ],
    "cursor": 0,
    "has_more": false
  }
}

Que signifient les sources de trafic ?

impression_sources classe les endroits où les spectateurs ont découvert la publication, de la plus grande part à la plus petite, chaque entrée étant un impression_source avec son pourcentage. TikTok documente ces valeurs :

  • For You : le fil For You.
  • Follow : le fil Follow.
  • Sound : les pages de sons.
  • Personal Profile : les pages de profil.
  • Search : les pages de recherche.
  • Direct Message : les messages directs, lorsque TikTok Studio affiche ces données pour le compte.
  • Others : tout le reste.

Quelles répartitions des spectateurs existe-t-il ?

Quatre, qui décrivent toutes les personnes ayant regardé cette publication plutôt que les abonnés du compte, et qui nécessitent toutes video.insights :

  • audience_genders : parts des spectateurs par genre, Female, Male ou Other.
  • audience_countries : jusqu'à 10 pays ou régions, sous forme de codes ISO 3166-1 alpha-2.
  • audience_cities : jusqu'à 10 villes, nommées comme US Cincinnati.
  • audience_types : NEW_VIEWER et RETURN_VIEWER, et FOLLOWER_PERCENT contre NON_FOLLOWER_PERCENT.

Quelles métriques dépendent du type de compte ?

Quelques clics et visites de profil proviennent de Business Analytics de TikTok et exigent plus qu'un compte personnel. profile_views, les visites de profil générées par une publication, nécessite un compte avec Advanced Access ou un Verified Business Account. website_clicks, phone_number_clicks, lead_submissions, app_download_clicks, email_clicks et address_clicks nécessitent un Verified Business Account.

Pourquoi une métrique peut-elle manquer ou arriver en retard ?

Parce que TikTok calcule la plupart d'entre elles hors ligne et seulement à partir de TikTok Analytics. Les compteurs et les métriques de visionnage ont généralement 24 à 48 heures de retard, alors que item_id, la légende et les liens sont en temps réel. La portée, le temps de visionnage, les sources de trafic et audience_countries peuvent manquer pour une vidéo que personne n'a vue, aimée, commentée ni partagée pendant 7 jours ; le conseil de TikTok est d'interagir avec elle et de réessayer après 24 à 48 heures. Les données cessent de se mettre à jour 365 jours après la publication, et les publications filtrées pour infraction, comme un droit d'auteur musical, ne sont pas renvoyées.

Comment easyCoexistence lit-il les métriques d'une vidéo ?

Avec get_social_insights : donnez l'item_id de la vidéo comme object_id et les noms de champs comme metrics, et l'outil renvoie les champs de cette publication, en cherchant parmi les 20 publications les plus récentes du compte. Pour une publication plus ancienne, votre propre code appelle business/video/list/ avec fields et filters.video_ids comme paramètres, en utilisant le token fourni par get_social_credentials.

One video's metrics through MCP
get_social_insights {
  "account_id": "<ACCOUNT_ID>",
  "object_id": "<ITEM_ID>",
  "metrics": ["video_views", "reach", "average_time_watched", "full_video_watched_rate", "impression_sources"]
}

Erreurs courantes

  • Supposer une seule échelle pour chaque pourcentage. Les exemples de TikTok donnent impression_sources sous forme de fractions dont la somme vaut 1, alors que son exemple audience_cities affiche des valeurs comme 17.4921.
  • Demander plusieurs champs sans item_id. La référence de TikTok avertit qu'une telle requête peut échouer.
  • Attendre la portée d'une vieille vidéo peu regardée. TikTok peut laisser vides la portée, le temps de visionnage et les sources de trafic après 7 jours sans vues, likes, commentaires ni partages.
  • Comparer les métriques d'une publication avec les métriques de compte quotidiennes. Les chiffres d'une publication couvrent toute sa durée de vie, alors que les métriques de compte arrivent par jour sur 60 jours au maximum.
Faire cela avec EasyCoexistence

Pour les publications plus anciennes, get_social_credentials donne à votre propre code le token du compte. De US$ 9 à US$ 0,75 par connexion et par mois, en baisse à mesure que vous ajoutez des connexions, avec les 3 premiers jours en essai gratuit.

Questions fréquemment posées

L'API TikTok donne-t-elle le temps de visionnage par vidéo ?

Oui. total_time_watched et average_time_watched sont renvoyés en secondes par /business/video/list/, pour les tokens disposant du scope video.insights.

Comment obtenir le taux de complétion d'une vidéo TikTok via l'API ?

Demandez full_video_watched_rate dans fields sur /business/video/list/. TikTok le définit comme le pourcentage de spectateurs qui vont jusqu'au bout de la vidéo.

Pourquoi la portée et le temps de visionnage sont-ils vides pour ma vidéo TikTok ?

TikTok peut les omettre pour une vidéo sans vues, likes, commentaires ni partages au cours des 7 derniers jours, et les données récentes ont 24 à 48 heures de retard.

L'API peut-elle renvoyer les métriques d'une seule vidéo TikTok ?

Oui. Passez son ID dans filters.video_ids, avec item_id et les métriques voulues dans fields.

Poursuivre la lecture

Connectez votre premier canal en deux minutes.

Aucune validation de plateforme à attendre. Connectez WhatsApp, Instagram, TikTok ou un autre canal, puis demandez à votre IA de publier, de répondre ou de faire un rapport, et regardez-la travailler.

  • 3 jours gratuits
  • Résiliable à tout moment
  • API officielles uniquement
  • Supervisé 24/7

Vérifié le