AccediInizia la prova gratuita
easyCoexistence API ufficiali

Metriche video TikTok via API: visualizzazioni, tempo di visione e completamento

L'API for Business di TikTok restituisce le metriche cumulative di ogni post da GET /business/video/list/, richieste per nome in fields: video_views, reach, likes, comments, shares e favorites, total_time_watched e average_time_watched in secondi, full_video_watched_rate, video_view_retention, impression_sources e i dettagli sugli spettatori come audience_countries. La maggior parte dei conteggi arriva con un ritardo da 24 a 48 ore e smette di aggiornarsi 365 giorni dopo la pubblicazione.

easyCoexistence legge le metriche di un video TikTok con get_social_insights da Claude, ChatGPT o dal tuo codice: indica i campi che vuoi, come video_views, reach o full_video_watched_rate, e l'item_id del video.

video.insights

Lo scope necessario per tempo di visione, completamento, ritenzione, fonti di traffico e dettagli sugli spettatori è video.insights; i conteggi di base richiedono video.list.

7 days

Il periodo di inattività dopo il quale copertura, tempo di visione, fonti di traffico e audience_countries possono mancare per un video.

10

La maggior parte delle voci nelle liste audience_countries e audience_cities di un video.

24 to 48 h

Ritardo abituale di video_views, likes, reach, tempo di visione e fonti di traffico, in UTC.

Quali metriche ha un video?

GET /business/video/list/ restituisce questi dati per ogni post indicato in fields, aggregati su tutta la vita del post e non sulla finestra di 60 giorni delle metriche dell'account. Conteggi come visualizzazioni e mi piace richiedono lo scope video.list sul token, mentre i dati su visione, completamento e ritenzione richiedono 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

Come si richiedono?

Indicale in fields, un array JSON che deve includere item_id ogni volta che elenca più di un campo, e scegli i post con filters.video_ids. Senza il filtro, l'endpoint scorre i post dell'account, fino a 20 alla volta:

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

Com'è fatta la risposta?

Un array videos con un oggetto per post e i campi richiesti, più cursor e has_more per la paginazione. L'esempio di TikTok, abbreviato, mostra le unità: tempi di visione in secondi con fino a tre decimali, e full_video_watched_rate come decimale, qui 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
  }
}

Cosa significano le fonti di traffico?

impression_sources classifica da dove gli spettatori hanno scoperto il post, dalla quota più grande alla più piccola, e ogni voce è un impression_source con la sua percentuale. TikTok documenta questi valori:

  • For You: il feed For You.
  • Follow: il feed Follow.
  • Sound: le pagine dei suoni.
  • Personal Profile: le pagine profilo.
  • Search: le pagine di ricerca.
  • Direct Message: i messaggi diretti, quando TikTok Studio mostra questi dati per l'account.
  • Others: tutto il resto.

Quali dettagli sugli spettatori ci sono?

Quattro, tutti riferiti alle persone che hanno guardato quel post e non ai follower dell'account, e tutti richiedono video.insights:

  • audience_genders: quote di spettatori per genere, Female, Male o Other.
  • audience_countries: fino a 10 paesi o regioni, come codici ISO 3166-1 alpha-2.
  • audience_cities: fino a 10 città, con nomi come US Cincinnati.
  • audience_types: NEW_VIEWER e RETURN_VIEWER, e FOLLOWER_PERCENT rispetto a NON_FOLLOWER_PERCENT.

Quali metriche dipendono dal tipo di account?

Alcuni clic e visite al profilo provengono da Business Analytics di TikTok e richiedono più di un account personale. profile_views, le visite al profilo generate da un post, richiede un account con Advanced Access o un Verified Business Account. website_clicks, phone_number_clicks, lead_submissions, app_download_clicks, email_clicks e address_clicks richiedono un Verified Business Account.

Perché una metrica può mancare o arrivare in ritardo?

Perché TikTok calcola la maggior parte di esse offline e solo da TikTok Analytics. Conteggi e metriche di visione di solito arrivano con un ritardo da 24 a 48 ore, mentre item_id, caption e links sono in tempo reale. Copertura, tempo di visione, fonti di traffico e audience_countries possono mancare per un video che nessuno ha visto, a cui nessuno ha messo mi piace, commentato o condiviso per 7 giorni; il consiglio di TikTok è interagire con il video e riprovare dopo 24 o 48 ore. I dati smettono di aggiornarsi 365 giorni dopo la pubblicazione, e i post filtrati per violazioni, come quelle sul copyright musicale, non vengono restituiti.

Come easyCoexistence legge le metriche di un video?

Con get_social_insights: passa l'item_id del video come object_id e i nomi dei campi come metrics, e restituisce i campi di quel post, cercando tra i 20 post più recenti dell'account. Per un post più vecchio, il tuo codice chiama business/video/list/ con fields e filters.video_ids come parametri, usando il token di 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"]
}

Errori comuni

  • Presumere una sola scala per ogni percentuale. Gli esempi di TikTok mostrano impression_sources come frazioni che sommano a 1, mentre l'esempio di audience_cities riporta valori come 17.4921.
  • Richiedere più campi senza item_id. Il riferimento di TikTok avverte che una richiesta del genere può fallire.
  • Aspettarsi la copertura per un video vecchio e poco attivo. TikTok può lasciare vuoti copertura, tempo di visione e fonti di traffico dopo 7 giorni senza visualizzazioni, mi piace, commenti o condivisioni.
  • Confrontare le metriche dei post con quelle giornaliere dell'account. Le cifre di un post coprono tutta la sua vita, mentre le metriche dell'account arrivano per giorno fino a 60 giorni.
Farlo con EasyCoexistence

Per i post più vecchi, get_social_credentials fornisce al tuo codice il token dell'account. US$ 9 a US$ 0,75 per connessione al mese, con il prezzo che scende man mano che aggiungi connessioni, e i primi 3 giorni di prova gratuita.

Domande frequenti

L'API di TikTok restituisce il tempo di visione per video?

Sì. total_time_watched e average_time_watched arrivano in secondi da /business/video/list/, per i token con lo scope video.insights.

Come ottengo il tasso di completamento di un video TikTok tramite API?

Richiedi full_video_watched_rate in fields su /business/video/list/. TikTok lo definisce come la percentuale di spettatori che finiscono di guardare il video.

Perché copertura e tempo di visione sono vuoti per il mio video TikTok?

TikTok può ometterli per un video senza visualizzazioni, mi piace, commenti o condivisioni negli ultimi 7 giorni, e i dati recenti arrivano con un ritardo da 24 a 48 ore.

L'API può restituire le metriche di un singolo video TikTok?

Sì. Passa il suo ID in filters.video_ids, con item_id e le metriche che ti servono in fields.

Continua a leggere

Collega il tuo primo canale in due minuti.

Nessuna revisione delle piattaforme da aspettare. Collega WhatsApp, Instagram, TikTok o un altro canale, poi chiedi alla tua AI di pubblicare, rispondere o fare un report, e guardala al lavoro.

  • 3 giorni gratis
  • Disdici quando vuoi
  • Solo API ufficiali
  • Monitorato 24/7

Verificato il