Conectați-văÎncepeți perioada de probă gratuită
easyCoexistence API-uri oficiale

Metricile video TikTok prin API: vizualizări, timp de vizionare și finalizare

API-ul for Business al TikTok returnează metricile de durată de viață ale fiecărei postări de la GET /business/video/list/, cerute prin numele lor în fields: video_views, reach, likes, comments, shares și favorites, total_time_watched și average_time_watched în secunde, full_video_watched_rate, video_view_retention, impression_sources și defalcările pe spectatori, precum audience_countries. Majoritatea numărătorilor sosesc cu 24 până la 48 de ore întârziere și nu se mai actualizează după 365 de zile de la publicare.

easyCoexistence citește metricile unui video TikTok cu get_social_insights din Claude, ChatGPT sau propriul cod: numiți câmpurile dorite, precum video_views, reach sau full_video_watched_rate, și dați item_id-ul videoclipului.

video.insights

Scope-ul necesar pentru timpul de vizionare, finalizare, retenție, surse de trafic și defalcările pe spectatori; numărătorile de bază cer video.list.

7 days

Perioada de inactivitate după care acoperirea, timpul de vizionare, sursele de trafic și audience_countries pot lipsi pentru un video.

10

Majoritatea intrărilor din listele audience_countries și audience_cities ale unui video.

24 to 48 h

Întârzierea obișnuită pentru video_views, likes, reach, timpul de vizionare și sursele de trafic, în UTC.

Ce metrici are un video?

GET /business/video/list/ returnează acestea pentru fiecare postare numită în fields, agregate pe întreaga durată de viață a postării, nu pe fereastra de 60 de zile a metricilor contului. Numărătorile precum vizualizările și aprecierile necesită scope-ul video.list pe token, în timp ce cifrele de vizionare, finalizare și retenție au nevoie de 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

Cum le cereți?

Numiți-le în fields, un array JSON care trebuie să includă item_id ori de câte ori listează mai mult de un câmp, și alegeți postările cu filters.video_ids. Fără filtru, endpoint-ul parcurge postările contului, până la 20 o dată:

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

Cum arată răspunsul?

Un array videos cu un obiect pentru fiecare postare și câmpurile cerute, plus cursor și has_more pentru paginare. Exemplul TikTok, redus, arată unitățile: timpii de vizionare în secunde, cu până la trei zecimale, iar full_video_watched_rate ca zecimală, aici 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
  }
}

Ce înseamnă sursele de trafic?

impression_sources ordonează locurile de unde spectatorii au descoperit postarea, de la cea mai mare pondere la cea mai mică, fiecare intrare fiind un impression_source cu procentul său. TikTok documentează aceste valori:

  • For You: fluxul For You.
  • Follow: fluxul Follow.
  • Sound: paginile de sunete.
  • Personal Profile: paginile de profil.
  • Search: paginile de căutare.
  • Direct Message: mesajele directe, atunci când TikTok Studio afișează aceste date pentru cont.
  • Others: orice altceva.

Ce defalcări ale spectatorilor există?

Patru, toate descriind persoanele care au urmărit acea postare, nu urmăritorii contului, și toate necesită video.insights:

  • audience_genders: ponderile spectatorilor după gen, Female, Male sau Other.
  • audience_countries: până la 10 țări sau regiuni, ca coduri ISO 3166-1 alpha-2.
  • audience_cities: până la 10 orașe, scrise ca US Cincinnati.
  • audience_types: NEW_VIEWER și RETURN_VIEWER, precum și FOLLOWER_PERCENT față de NON_FOLLOWER_PERCENT.

Ce metrici depind de tipul contului?

Câteva clicurile și vizitele la profil provin din Business Analytics de la TikTok și necesită mai mult decât un cont personal. profile_views, vizitele la profil generate de o postare, necesită un cont cu Advanced Access sau un Verified Business Account. website_clicks, phone_number_clicks, lead_submissions, app_download_clicks, email_clicks și address_clicks necesită un Verified Business Account.

De ce poate lipsi sau întârzia o metrică?

Pentru că TikTok calculează majoritatea offline și doar din TikTok Analytics. Numărătorile și metricile de vizionare întârzie de obicei 24 până la 48 de ore, în timp ce item_id, caption și links sunt în timp real. Acoperirea, timpul de vizionare, sursele de trafic și audience_countries pot lipsi pentru un video pe care nimeni nu l-a vizionat, apreciat, comentat sau distribuit timp de 7 zile; sfatul TikTok este să interacționați cu el și să reîncercați după 24 până la 48 de ore. Datele nu se mai actualizează după 365 de zile de la publicare, iar postările filtrate pentru încălcări, cum ar fi drepturile de autor asupra muzicii, nu sunt returnate.

Cum citește easyCoexistence metricile unui video?

Cu get_social_insights: dați item_id-ul videoclipului drept object_id și numele câmpurilor drept metrics, iar instrumentul returnează câmpurile acelei postări, căutând printre ultimele 20 de postări ale contului. Pentru o postare mai veche, propriul cod apelează business/video/list/ cu fields și filters.video_ids ca parametri, folosind token-ul din 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"]
}

Greșeli frecvente

  • Presupunerea unei singure scale pentru toate procentele. Exemplele TikTok dau impression_sources ca fracții care adună 1, în timp ce exemplul pentru audience_cities arată valori precum 17.4921.
  • Solicitarea mai multor câmpuri fără item_id. Referința TikTok avertizează că o astfel de cerere poate eșua.
  • Așteptarea unei acoperiri pentru un video vechi și liniștit. TikTok poate lăsa goale acoperirea, timpul de vizionare și sursele de trafic după 7 zile fără vizualizări, aprecieri, comentarii sau distribuiri.
  • Compararea metricilor postării cu metricile zilnice ale contului. Cifrele unei postări acoperă întreaga sa durată de viață, în timp ce metricile contului vin pe zi, pentru până la 60 de zile.
Faceți acest lucru cu EasyCoexistence

Pentru postările mai vechi, get_social_credentials oferă propriului cod token-ul contului. De la US$ 9 până la US$ 0.75 pe conexiune pe lună, scăzând pe măsură ce adăugați conexiuni, cu primele 3 zile gratuite.

Întrebări frecvente

API-ul TikTok oferă timpul de vizionare pe video?

Da. total_time_watched și average_time_watched vin în secunde de la /business/video/list/, pentru token-uri cu scope-ul video.insights.

Cum obțin rata de finalizare a unui video TikTok prin API?

Cereți full_video_watched_rate în fields pe /business/video/list/. TikTok o definește ca procentul spectatorilor care termină de vizionat videoclipul.

De ce sunt goale acoperirea și timpul de vizionare pentru videoclipul meu TikTok?

TikTok le poate omite pentru un video fără vizualizări, aprecieri, comentarii sau distribuiri în ultimele 7 zile, iar datele recente întârzie 24 până la 48 de ore.

Poate API-ul să returneze metricile unui anumit video TikTok?

Da. Transmiteți ID-ul său în filters.video_ids, cu item_id și metricile dorite în fields.

Continuați să citiți

Conectați primul canal în două minute.

Fără recenzii de platformă de așteptat. Conectați WhatsApp, Instagram, TikTok sau alt canal, apoi cereți AI-ului să publice, să răspundă sau să raporteze și urmăriți-l cum lucrează.

  • 3 zile gratuit
  • Anulați oricând
  • Doar API-uri oficiale
  • Monitorizat 24/7

Verificat la