Métricas de vídeo do TikTok através da API: visualizações, tempo de visualização e conclusão
A API for Business do TikTok devolve as métricas acumuladas de cada publicação a partir de GET /business/video/list/, pedidas pelo nome em fields: video_views, reach, likes, comments, shares e favorites, total_time_watched e average_time_watched em segundos, full_video_watched_rate, video_view_retention, impression_sources e detalhes dos espectadores, como audience_countries. A maioria das contagens chega com 24 a 48 horas de atraso e deixa de ser atualizada 365 dias após a publicação.
A easyCoexistence lê as métricas de um vídeo do TikTok com get_social_insights, a partir do Claude, do ChatGPT ou do seu próprio código: indique os campos que quer, como video_views, reach ou full_video_watched_rate, e o item_id do vídeo.
Âmbito necessário para o tempo de visualização, a conclusão, a retenção, as origens do tráfego e os detalhes dos espectadores; as contagens básicas precisam de video.list.
Período de inatividade após o qual o alcance, o tempo de visualização, as origens do tráfego e audience_countries podem faltar num vídeo.
A maioria das entradas nas listas audience_countries e audience_cities de um vídeo.
Atraso habitual de video_views, likes, alcance, tempo de visualização e origens do tráfego, em UTC.
Que métricas tem um vídeo?
GET /business/video/list/ devolve estas métricas para cada publicação indicada em fields, agregadas durante toda a vida da publicação e não na janela de 60 dias das métricas da conta. Contagens como visualizações e likes precisam do scope video.list no token, enquanto os valores de tempo de visualização, conclusão e retenção precisam de video.insights:
Como se pedem?
Indique-as em fields, um array JSON que tem de incluir item_id sempre que liste mais do que um campo, e escolha as publicações com filters.video_ids. Sem o filtro, o endpoint percorre as publicações da conta, até 20 de cada vez:
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>"]}'Como é a resposta?
Um array videos com um objeto por publicação e os campos pedidos, mais cursor e has_more para a paginação. O exemplo do próprio TikTok, resumido, mostra as unidades: tempos de visualização em segundos com até três casas decimais, e full_video_watched_rate como decimal, 0.0237 neste caso:
{
"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
}
}O que significam as origens do tráfego?
impression_sources ordena os locais onde os espectadores descobriram a publicação, do maior para o menor peso, cada entrada um impression_source com a respetiva percentagem. O TikTok documenta estes valores:
- For You: o feed For You.
- Follow: o feed Follow.
- Sound: páginas de sons.
- Personal Profile: páginas de perfil.
- Search: páginas de pesquisa.
- Direct Message: mensagens diretas, quando o TikTok Studio mostra esses dados para a conta.
- Others: tudo o resto.
Que detalhes dos espectadores existem?
Quatro, todos a descrever as pessoas que viram essa publicação e não os seguidores da conta, e todos a precisar de video.insights:
audience_genders: percentagens de espectadores por género, Female, Male ou Other.audience_countries: até 10 países ou regiões, em códigos ISO 3166-1 alpha-2.audience_cities: até 10 cidades, com nomes como US Cincinnati.audience_types:NEW_VIEWEReRETURN_VIEWER, eFOLLOWER_PERCENTface aNON_FOLLOWER_PERCENT.
Que métricas dependem do tipo de conta?
Alguns cliques e visitas ao perfil vêm do Business Analytics do TikTok e exigem mais do que uma conta pessoal. profile_views, as visitas ao perfil geradas por uma publicação, precisa de uma conta com Advanced Access ou de uma Conta Business Verificada. website_clicks, phone_number_clicks, lead_submissions, app_download_clicks, email_clicks e address_clicks precisam de uma Conta Business Verificada.
Porque é que uma métrica pode faltar ou chegar tarde?
Porque o TikTok calcula a maioria delas offline e apenas a partir do TikTok Analytics. As contagens e as métricas de visualização costumam atrasar 24 a 48 horas, enquanto item_id, caption e links são em tempo real. O alcance, o tempo de visualização, as origens do tráfego e audience_countries podem faltar numa publicação que ninguém viu, gostou, comentou ou partilhou durante 7 dias; a sugestão do TikTok é interagir com ela e voltar a tentar 24 a 48 horas depois. Os dados deixam de ser atualizados 365 dias após a publicação, e as publicações filtradas por violações, como direitos de autor musicais, não são devolvidas.
Como é que a easyCoexistence lê as métricas de um vídeo?
Com get_social_insights: indique o item_id do vídeo como object_id e os nomes dos campos como metrics, e devolve os campos dessa publicação, procurando entre as 20 publicações mais recentes da conta. Para uma publicação mais antiga, o seu próprio código chama business/video/list/ com fields e filters.video_ids como parâmetros, usando o token de get_social_credentials.
get_social_insights {
"account_id": "<ACCOUNT_ID>",
"object_id": "<ITEM_ID>",
"metrics": ["video_views", "reach", "average_time_watched", "full_video_watched_rate", "impression_sources"]
}Erros comuns
- Assumir uma só escala para todas as percentagens. Os exemplos do TikTok dão impression_sources como frações que somam 1, enquanto o exemplo de audience_cities mostra valores como 17.4921.
- Pedir vários campos sem item_id. A referência do TikTok avisa que um pedido assim pode falhar.
- Esperar alcance num vídeo antigo e sem movimento. O TikTok pode deixar vazios o alcance, o tempo de visualização e as origens do tráfego após 7 dias sem visualizações, likes, comentários ou partilhas.
- Comparar as métricas de uma publicação com as métricas diárias da conta. Os valores de uma publicação cobrem toda a sua vida, enquanto as métricas da conta chegam por dia, até 60 dias.
Para as publicações mais antigas, get_social_credentials dá ao seu próprio código o token da conta. De US$ 9 a US$ 0.75 por ligação por mês, a descer à medida que acrescenta ligações, com os primeiros 3 dias grátis.
Perguntas frequentes
A API do TikTok devolve o tempo de visualização por vídeo?
Sim. total_time_watched e average_time_watched chegam em segundos a partir de /business/video/list/, para tokens com o âmbito video.insights.
Como obtenho a taxa de conclusão de um vídeo do TikTok através da API?
Peça full_video_watched_rate em fields em /business/video/list/. O TikTok define-a como a percentagem de espectadores que veem o vídeo até ao fim.
Porque é que o alcance e o tempo de visualização aparecem vazios no meu vídeo do TikTok?
O TikTok pode omiti-los num vídeo sem visualizações, likes, comentários ou partilhas nos últimos 7 dias, e os dados recentes atrasam 24 a 48 horas.
A API consegue devolver métricas de um vídeo específico do TikTok?
Sim. Indique o respetivo ID em filters.video_ids, com item_id e as métricas que pretende em fields.
Continue a ler
Ligue o seu primeiro canal em dois minutos.
Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorizado 24/7
Verificado em