InloggenGratis proefperiode starten
easyCoexistence Officiële API's

TikTok-videometrics via de API: weergaven, kijktijd en voltooiing

De API for Business van TikTok geeft de levensduurstatistieken van elke post terug via GET /business/video/list/, opgevraagd met de naam in fields: video_views, reach, likes, comments, shares en favorites, total_time_watched en average_time_watched in seconden, full_video_watched_rate, video_view_retention, impression_sources en kijkersuitsplitsingen zoals audience_countries. De meeste tellingen komen 24 tot 48 uur te laat binnen en stoppen met bijwerken 365 dagen na publicatie.

easyCoexistence leest de metrics van een TikTok-video met get_social_insights vanuit Claude, ChatGPT of je eigen code: noem de velden die je wilt, zoals video_views, reach of full_video_watched_rate, en geef het item_id van de video.

video.insights

Scope nodig voor kijktijd, voltooiing, retentie, herkomst van het verkeer en kijkersuitsplitsingen; de basistellingen vragen video.list.

7 days

Inactiviteit waarna bereik, kijktijd, herkomst van het verkeer en audience_countries voor een video kunnen ontbreken.

10

De meeste vermeldingen in de lijsten audience_countries en audience_cities van een video.

24 to 48 h

Gebruikelijke vertraging voor video_views, likes, reach, kijktijd en herkomst van het verkeer, in UTC.

Welke metrics heeft een video?

GET /business/video/list/ geeft deze terug voor elke post die in fields is genoemd, geaggregeerd over de volledige levensduur van de post in plaats van het venster van 60 dagen van accountmetrics. Tellingen zoals weergaven en likes vereisen de video.list-scope op het token, terwijl de cijfers voor kijktijd, voltooiing en retentie de video.insights-scope vereisen:

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

Hoe vraag je ze op?

Noem ze in fields, een JSON-array die item_id moet bevatten zodra er meer dan één veld in staat, en kies posts met filters.video_ids. Zonder het filter bladert het endpoint door de posts van het account, 20 tegelijk:

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>"]}'

Hoe ziet het antwoord eruit?

Een array videos met per post één object en de gevraagde velden, plus cursor en has_more voor paginering. Het eigen voorbeeld van TikTok, ingekort, laat de eenheden zien: kijktijden in seconden met maximaal drie decimalen, en full_video_watched_rate als decimaal getal, hier 0.0237:

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
  }
}

Wat betekenen de herkomstbronnen?

impression_sources rangschikt waar kijkers de post hebben ontdekt, van het grootste aandeel naar het kleinste, elk item een impression_source met zijn percentage. TikTok documenteert deze waarden:

  • For You: de For You-feed.
  • Follow: de Volgfeed.
  • Sound: geluidspagina's.
  • Personal Profile: profielpagina's.
  • Search: zoekpagina's.
  • Direct Message: directe berichten, wanneer TikTok Studio die gegevens voor het account toont.
  • Others: al het overige.

Welke kijkersuitsplitsingen zijn er?

Vier, alle beschrijven de mensen die die post hebben bekeken en niet de volgers van het account, en alle vereisen video.insights:

  • audience_genders: aandelen kijkers per geslacht, Female, Male of Other.
  • audience_countries: tot 10 landen of regio's, als ISO 3166-1 alpha-2-codes.
  • audience_cities: tot 10 steden, genoemd zoals US Cincinnati.
  • audience_types: NEW_VIEWER en RETURN_VIEWER, en FOLLOWER_PERCENT tegenover NON_FOLLOWER_PERCENT.

Welke metrics hangen af van het accounttype?

Een paar klikken en profielbezoeken komen van TikTok Business Analytics en vereisen meer dan een persoonlijk account. profile_views, de profielbezoeken die een post heeft opgeleverd, vereist een account met Advanced Access of een Verified Business Account. website_clicks, phone_number_clicks, lead_submissions, app_download_clicks, email_clicks en address_clicks vereisen een Verified Business Account.

Waarom kan een metric ontbreken of te laat zijn?

Omdat TikTok de meeste offline berekent en alleen uit TikTok Analytics. Tellingen en kijkmetrics lopen meestal 24 tot 48 uur achter, terwijl item_id, bijschrift en links realtime zijn. Bereik, kijktijd, herkomst van het verkeer en audience_countries kunnen ontbreken voor een video die 7 dagen lang niemand heeft bekeken, geliked, becommentarieerd of gedeeld; TikTok adviseert om er interactie mee te hebben en het na 24 tot 48 uur opnieuw te proberen. Gegevens stoppen met bijwerken 365 dagen na publicatie, en posts die gefilterd zijn wegens overtredingen, zoals auteursrechtelijke muziek, worden niet teruggegeven.

Hoe leest easyCoexistence de metrics van een video?

Met get_social_insights: geef het item_id van de video als object_id en de veldnamen als metrics, en het geeft de velden van die post terug, gezocht onder de 20 meest recente posts van het account. Voor een oudere post roept je eigen code business/video/list/ aan met fields en filters.video_ids als parameters, met het token uit 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"]
}

Veelgemaakte fouten

  • Aannemen dat één schaal geldt voor elk percentage. De voorbeelden van TikTok geven impression_sources als breuken die optellen tot 1, terwijl het audience_cities-voorbeeld waarden toont zoals 17.4921.
  • Meerdere velden opvragen zonder item_id. De referentie van TikTok waarschuwt dat zo'n verzoek mogelijk mislukt.
  • Bereik verwachten bij een oude, rustige video. TikTok kan bereik, kijktijd en herkomst van het verkeer leeg laten na 7 dagen zonder weergaven, likes, reacties of keren gedeeld.
  • Postmetrics vergelijken met dagelijkse accountmetrics. De cijfers van een post dekken de volledige levensduur, terwijl accountmetrics per dag komen, tot 60 dagen terug.
Dit doen met EasyCoexistence

Voor oudere posts geeft get_social_credentials je eigen code het token van het account. Van US$ 9 tot US$ 0,75 per verbinding per maand, dalend naarmate je meer verbindingen toevoegt, met de eerste 3 dagen gratis.

Veelgestelde vragen

Geeft de TikTok API kijktijd per video?

Ja. total_time_watched en average_time_watched komen in seconden uit /business/video/list/, voor tokens met de video.insights-scope.

Hoe krijg ik het voltooiingspercentage van een TikTok-video via de API?

Vraag full_video_watched_rate op in fields bij /business/video/list/. TikTok definieert het als het percentage kijkers dat de video helemaal uitkijkt.

Waarom zijn bereik en kijktijd leeg voor mijn TikTok-video?

TikTok kan ze weglaten voor een video zonder weergaven, likes, reacties of gedeelde posts in de laatste 7 dagen, en recente gegevens lopen 24 tot 48 uur achter.

Kan de API metrics van één specifieke TikTok-video teruggeven?

Ja. Geef het ID mee in filters.video_ids, met item_id en de gewenste metrics in fields.

Lees verder

Koppel je eerste kanaal in twee minuten.

Geen platformbeoordelingen om op te wachten. Verbind WhatsApp, Instagram, TikTok of een ander kanaal, vraag je AI om te posten, te reageren of een rapport te maken, en zie het aan het werk.

  • 3 dagen gratis
  • Op elk moment opzegbaar
  • Alleen officiële API's
  • 24/7 bewaakt

Geverifieerd op