EntrarComeçar teste grátis
easyCoexistence APIs oficiais

Métricas de vídeo do TikTok pela API: visualizações, tempo assistido e conclusão

A API for Business do TikTok devolve as métricas acumuladas de cada post 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 detalhamentos de audiência como audience_countries. A maioria das contagens chega com atraso de 24 a 48 horas e deixa de ser atualizada 365 dias após a publicação.

O easyCoexistence lê as métricas de um vídeo do TikTok com get_social_insights, pelo Claude, pelo ChatGPT ou pelo seu próprio código: indique os campos que quer, como video_views, reach ou full_video_watched_rate, e informe o item_id do vídeo.

video.insights

Escopo necessário para tempo assistido, conclusão, retenção, origens de tráfego e detalhamentos de espectadores; as contagens básicas exigem video.list.

7 days

Inatividade após a qual alcance, tempo assistido, origens de tráfego e audience_countries podem faltar em um vídeo.

10

A maioria dos itens nas listas audience_countries e audience_cities de um vídeo.

24 to 48 h

Atraso usual para video_views, likes, reach, tempo assistido e origens de tráfego, em UTC.

Quais métricas um vídeo tem?

GET /business/video/list/ devolve estas para cada post indicado em fields, agregadas pela vida inteira do post, e não pela janela de 60 dias das métricas da conta. Contagens como visualizações e curtidas exigem o escopo video.list no token, enquanto os números de tempo assistido, conclusão e retenção exigem 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

Como solicitá-las?

Indique-as em fields, um array JSON que deve incluir item_id sempre que listar mais de um campo, e escolha os posts com filters.video_ids. Sem o filtro, o endpoint percorre os posts da conta, até 20 por vez:

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

Como é a resposta?

Um array videos com um objeto por post e os campos pedidos, mais cursor e has_more para a paginação. O exemplo do próprio TikTok, resumido, mostra as unidades: tempos assistidos em segundos com até três casas decimais, e full_video_watched_rate como decimal, 0.0237 neste caso:

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

O que significam as origens de tráfego?

impression_sources ordena de onde os espectadores descobriram o post, da maior para a menor fatia, com cada item sendo um impression_source com sua porcentagem. O TikTok documenta estes valores:

  • For You: o feed For You.
  • Follow: o feed Follow.
  • Sound: páginas de som.
  • Personal Profile: páginas de perfil.
  • Search: páginas de busca.
  • Direct Message: mensagens diretas, quando o TikTok Studio mostra esses dados para a conta.
  • Others: todo o restante.

Quais detalhamentos de espectadores existem?

Quatro, todos descrevendo as pessoas que assistiram àquele post e não os seguidores da conta, e todos exigindo video.insights:

  • audience_genders: parcelas 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 no formato US Cincinnati.
  • audience_types: NEW_VIEWER e RETURN_VIEWER, e FOLLOWER_PERCENT em relação a NON_FOLLOWER_PERCENT.

Quais 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 que um post gerou, exige uma conta com Advanced Access ou uma Verified Business Account. website_clicks, phone_number_clicks, lead_submissions, app_download_clicks, email_clicks e address_clicks exigem uma Verified Business Account.

Por que uma métrica pode faltar ou chegar atrasada?

Porque o TikTok calcula a maioria delas offline e somente a partir do TikTok Analytics. Contagens e métricas de visualização costumam atrasar de 24 a 48 horas, enquanto item_id, legenda e links são em tempo real. Alcance, tempo assistido, origens de tráfego e audience_countries podem faltar para um vídeo que ninguém visualizou, curtiu, comentou ou compartilhou por 7 dias; a dica do TikTok é interagir com ele e repetir a consulta após 24 a 48 horas. Os dados deixam de ser atualizados 365 dias após a publicação, e posts filtrados por violações, como direitos autorais de música, não são devolvidos.

Como o easyCoexistence lê as métricas de um vídeo?

Com get_social_insights: informe o item_id do vídeo como object_id e os nomes dos campos como metrics, e ele devolve os campos desse post, procurando entre os 20 posts mais recentes da conta. Para um post mais antigo, 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.

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

Erros comuns

  • Supor uma única escala para todas as porcentagens. Os exemplos do TikTok trazem 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 alerta que essa requisição pode falhar.
  • Esperar alcance de um vídeo antigo e parado. O TikTok pode deixar alcance, tempo assistido e origens de tráfego vazios após 7 dias sem visualizações, curtidas, comentários ou compartilhamentos.
  • Comparar métricas de post com métricas diárias da conta. As cifras de um post cobrem toda a sua vida, enquanto as métricas da conta vêm por dia, por até 60 dias.
Fazendo isso com o EasyCoexistence

Para posts mais antigos, get_social_credentials entrega ao seu próprio código o token da conta. De US$ 9 a US$ 0.75 por conexão por mês, com o valor caindo à medida que você adiciona conexões, e os 3 primeiros dias grátis.

O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.

Perguntas frequentes

A API do TikTok devolve o tempo assistido por vídeo?

Sim. total_time_watched e average_time_watched vêm em segundos de /business/video/list/, para tokens com o escopo video.insights.

Como obtenho a taxa de conclusão de um vídeo do TikTok pela API?

Peça full_video_watched_rate em fields em /business/video/list/. O TikTok a define como a porcentagem de espectadores que assistem ao vídeo até o fim.

Por que alcance e tempo assistido estão vazios no meu vídeo do TikTok?

O TikTok pode omiti-los em um vídeo sem visualizações, curtidas, comentários ou compartilhamentos nos últimos 7 dias, e os dados recentes atrasam de 24 a 48 horas.

A API pode devolver métricas de um vídeo específico do TikTok?

Sim. Passe o ID dele em filters.video_ids, com item_id e as métricas desejadas em fields.

Continue lendo

Conecte seu primeiro canal em dois minutos.

Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.

  • 3 dias grátis
  • Cancele quando quiser
  • Só APIs oficiais
  • Monitorado 24/7

Verificado em