Zaloguj sięRozpocznij bezpłatny okres próbny
easyCoexistence Oficjalne API

Metryki wideo TikTok przez API: wyświetlenia, czas oglądania i ukończenie

TikTok API for Business zwraca łączne metryki każdego posta od jego publikacji z GET /business/video/list/, wskazane po nazwie w fields: video_views, reach, likes, comments, shares i favorites, total_time_watched i average_time_watched w sekundach, full_video_watched_rate, video_view_retention, impression_sources oraz rozkłady widzów, takie jak audience_countries. Większość liczników dociera z opóźnieniem 24 do 48 godzin i przestaje się aktualizować 365 dni po publikacji.

easyCoexistence odczytuje metryki filmu TikTok przez get_social_insights z poziomu Claude, ChatGPT lub własnego kodu: wymieniasz pola, których chcesz, na przykład video_views, reach lub full_video_watched_rate, i podajesz item_id filmu.

video.insights

Zakres potrzebny do czasu oglądania, ukończenia, retencji, źródeł ruchu i rozkładów widzów; podstawowe liczniki wymagają video.list.

7 days

Okres bezczynności, po którym przy danym filmie mogą brakować zasięg, czas oglądania, źródła ruchu i audience_countries.

10

Większość wpisów na listach audience_countries i audience_cities danego filmu.

24 to 48 h

Typowe opóźnienie dla video_views, likes, reach, czasu oglądania i źródeł ruchu, w czasie UTC.

Jakie metryki ma film?

GET /business/video/list/ zwraca je dla każdego posta wskazanego w fields, zsumowane za całe życie posta, a nie za 60-dniowe okno metryk konta. Liczniki, takie jak wyświetlenia i polubienia, wymagają zakresu video.list w tokenie, a dane o oglądaniu, ukończeniu i retencji wymagają 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

Jak je zamówić?

Wymień je w fields, w tablicy JSON, która musi zawierać item_id, gdy wymienia więcej niż jedno pole, i wybierz posty za pomocą filters.video_ids. Bez tego filtra endpoint przechodzi przez posty konta, po 20 naraz:

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

Jak wygląda odpowiedź?

Tablica videos z jednym obiektem na post i żądanymi polami, plus cursor i has_more do stronicowania. Przykład TikToka, skrócony, pokazuje jednostki: czasy oglądania w sekundach z trzema miejscami po przecinku, a full_video_watched_rate jako ułamek dziesiętny, tutaj 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
  }
}

Co znaczą źródła ruchu?

impression_sources klasyfikuje, skąd widzowie odkryli post, od największego udziału do najmniejszego; każdy wpis to impression_source z procentem. TikTok dokumentuje te wartości:

  • For You: kanał For You.
  • Follow: kanał Follow.
  • Sound: strony dźwięku.
  • Personal Profile: strony profilu.
  • Search: strony wyszukiwania.
  • Direct Message: wiadomości bezpośrednie, gdy TikTok Studio pokazuje te dane dla konta.
  • Others: wszystko inne.

Jakie są rozkłady widzów?

Cztery, wszystkie opisują osoby, które obejrzały dany post, a nie obserwujących konto, i wszystkie wymagają video.insights:

  • audience_genders: udział widzów według płci: Female, Male lub Other.
  • audience_countries: do 10 krajów lub regionów, w kodach ISO 3166-1 alpha-2.
  • audience_cities: do 10 miast, zapisanych jak US Cincinnati.
  • audience_types: NEW_VIEWER i RETURN_VIEWER oraz FOLLOWER_PERCENT wobec NON_FOLLOWER_PERCENT.

Które metryki zależą od typu konta?

Kilka kliknięć i wizyt w profilu pochodzi z TikTok Business Analytics i wymaga więcej niż konta osobistego. profile_views, czyli wizyty w profilu wywołane przez post, wymaga konta z Advanced Access lub Verified Business Account. website_clicks, phone_number_clicks, lead_submissions, app_download_clicks, email_clicks i address_clicks wymagają Verified Business Account.

Dlaczego metryka może brakować lub się spóźniać?

Ponieważ TikTok liczy większość z nich offline i wyłącznie z TikTok Analytics. Liczniki i metryki oglądania zwykle opóźniają się o 24 do 48 godzin, podczas gdy item_id, opis i linki są w czasie rzeczywistym. Zasięg, czas oglądania, źródła ruchu i audience_countries mogą brakować przy filmie, którego nikt nie obejrzał, nie polubił, nie skomentował ani nie udostępnił przez 7 dni; wskazówka TikToka brzmi: zaangażuj się w ten film i ponów zapytanie po 24 do 48 godzinach. Dane przestają się aktualizować 365 dni po publikacji, a posty odfiltrowane za naruszenia, na przykład praw autorskich do muzyki, nie są zwracane.

Jak easyCoexistence odczytuje metryki filmu?

Za pomocą get_social_insights: podajesz item_id filmu jako object_id i nazwy pól jako metrics, a narzędzie zwraca pola tego posta, szukając wśród 20 najnowszych postów konta. Dla starszego posta Twój własny kod wywołuje business/video/list/ z fields i filters.video_ids jako parametrami, używając tokena z 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"]
}

Typowe błędy

  • Zakładanie jednej skali dla każdego procentu. Przykłady TikToka podają impression_sources jako ułamki sumujące się do 1, podczas gdy jego przykład audience_cities pokazuje wartości takie jak 17.4921.
  • Żądanie kilku pól bez item_id. Dokumentacja TikToka ostrzega, że takie żądanie może się nie udać.
  • Oczekiwanie zasięgu dla starego, cichego filmu. TikTok może pozostawić zasięg, czas oglądania i źródła ruchu puste po 7 dniach bez wyświetleń, polubień, komentarzy i udostępnień.
  • Porównywanie metryk posta z dziennymi metrykami konta. Dane posta obejmują całe jego życie, a metryki konta przychodzą dziennie przez maksymalnie 60 dni.
Z EasyCoexistence zrobisz to

Dla starszych postów get_social_credentials daje własnemu kodowi token konta. US$ 9 do US$ 0.75 za połączenie miesięcznie, z każdym kolejnym połączeniem taniej, z pierwszymi 3 dniami bezpłatnie.

Najczęściej zadawane pytania

Czy TikTok API zwraca czas oglądania dla każdego filmu?

Tak. total_time_watched i average_time_watched przychodzą w sekundach z /business/video/list/, dla tokenów z zakresem video.insights.

Jak przez API pobrać wskaźnik ukończenia filmu TikTok?

Zażądaj full_video_watched_rate w fields na /business/video/list/. TikTok definiuje go jako procent widzów, którzy obejrzeli film do końca.

Dlaczego zasięg i czas oglądania są puste dla mojego filmu TikTok?

TikTok może je pominąć dla filmu bez wyświetleń, polubień, komentarzy i udostępnień w ciągu ostatnich 7 dni, a świeże dane opóźniają się o 24 do 48 godzin.

Czy API może zwrócić metryki jednego konkretnego filmu TikTok?

Tak. Przekaż jego ID w filters.video_ids, a w fields podaj item_id i metryki, które chcesz.

Czytaj dalej

Połącz pierwszy kanał w dwie minuty.

Bez czekania na weryfikację przez platformy. Połącz WhatsApp, Instagram, TikTok lub inny kanał, a potem poproś swoją AI o opublikowanie posta, odpowiedź lub raport i zobacz, jak działa.

  • 3 dni za darmo
  • Rezygnacja w każdej chwili
  • Tylko oficjalne API
  • Monitorowanie 24/7

Zweryfikowano w