EntrarComeçar teste grátis
easyCoexistence APIs oficiais

Listando os vídeos de uma conta do TikTok pela API

A API for Business do TikTok lista os posts públicos de uma conta com GET /business/video/list/, a partir do mais recente, até 20 por página. Informe os campos que quer receber, como item_id, caption, share_url e video_views, e percorra as páginas com cursor enquanto has_more for true. filters.video_ids seleciona posts específicos, e cada item_id é o ID que as chamadas de comentário recebem.

A easyCoexistence lista os posts recentes de uma conta do TikTok com list_social_posts, a partir do Claude, do ChatGPT ou do seu próprio código, com item_id, caption, link e contagens de cada post, e get_social_credentials entrega ao seu próprio código o token para as páginas seguintes e outros campos.

20

Quantidade máxima de posts que /business/video/list/ retorna por página; max_count assume 10 por padrão.

Milliseconds

Unidade do cursor, um timestamp Unix em UTC; o endpoint retorna os posts publicados antes dele.

item_id

O campo padrão, que uma requisição com vários campos deve incluir; caso contrário, pode ocorrer um erro.

40/min

Chamadas permitidas por conta autorizada neste endpoint, como em cada endpoint da Accounts API.

O que o endpoint retorna?

Os posts públicos da conta: vídeos exibidos no perfil, posts de foto e texto, e vídeos Only show in ads, que rodam como anúncios sem aparecer no perfil. media_type distingue VIDEO de PHOTO, que cobre posts de foto e de texto. Posts que o TikTok filtrou por violações, como direitos autorais de música, ficam de fora da lista.

Como você faz a chamada?

Com GET e parâmetros na URL: business_id, fields como array JSON e, opcionalmente, filters, cursor e max_count, que assume 10 por padrão. O token vai no cabeçalho Access-Token, e o app de desenvolvedor precisa da permissão Get Account Media em TikTok Accounts:

List the latest posts
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","create_time","media_type","caption","share_url","thumbnail_url","video_views","likes","comments","shares"]' \
  --data-urlencode 'max_count=20'

Quais campos descrevem um post?

Além das métricas, que vão de video_views a impression_sources, a lista traz estes campos, todos no escopo video.list:

  • item_id: o ID do post, usado pelas chamadas de comentário e por filters.video_ids.
  • media_type: VIDEO, ou PHOTO para post de foto ou de texto.
  • is_ad: se o post está sendo usado em um anúncio.
  • create_time: quando o post foi publicado, em segundos Unix em UTC.
  • caption: a descrição do post, com as hashtags incluídas.
  • share_url: um link compartilhável, que se comporta de forma diferente no celular e no desktop.
  • embed_url: um link de player para outros sites, que não reproduz posts definidos como Friends ou Only you.
  • thumbnail_url: uma imagem de prévia temporária, cuja validade fica no parâmetro x-expires.
  • video_duration: a duração em segundos, com três casas decimais.

Como é uma página de resultados?

Um array videos na ordem em que o TikTok o devolve, além de cursor, o valor a enviar na próxima página, e has_more, que indica se há uma. create_time chega como string de segundos Unix. Exemplo do TikTok, reduzido aos campos descritivos e às contagens:

A page from /business/video/list/
{
  "code": 0,
  "message": "OK",
  "request_id": "2021080307532501024502410704A7306F",
  "data": {
    "videos": [
      {
        "item_id": "6990565363377392901",
        "create_time": "1627617835",
        "caption": "little coco",
        "share_url": "https://www.tiktok.com/@feather_in_the_w1nd/video/6990565363377392901?utm_campaign=tt4d_open_api&utm_source=6979330045630218242",
        "likes": 10,
        "comments": 2,
        "shares": 0,
        "video_views": 1231
      }
    ],
    "cursor": 0,
    "has_more": false
  }
}

Como funciona a paginação?

Por tempo. cursor assume por padrão o momento atual em milissegundos, então a primeira página traz os posts mais recentes, e cada resposta devolve o cursor da próxima requisição. Envie-o enquanto has_more for true. Um timestamp personalizado lista os posts publicados antes desse momento, e as regras de confiança e segurança do TikTok podem deixar uma página menor que max_count mesmo quando ainda há posts.

Every page, in Python
import json, requests

API = "https://business-api.tiktok.com/open_api/v1.3"

def all_posts(token: str, business_id: str, fields: list[str]):
    params = {"business_id": business_id, "fields": json.dumps(fields), "max_count": 20}
    while True:
        r = requests.get(f"{API}/business/video/list/", headers={"Access-Token": token},
                         params=params, timeout=30).json()
        if r["code"] != 0:
            raise RuntimeError(f"{r['code']}: {r['message']}")
        yield from r["data"].get("videos", [])
        if not r["data"].get("has_more"):
            return
        params["cursor"] = r["data"]["cursor"]

Como buscar posts específicos?

Com filters, um objeto JSON: video_ids lista os IDs de post a retornar, como os post_ids de um status de publicação. ad_post_only, válido apenas junto de video_ids, mantém somente os posts autorizados para anunciantes em Spark Ads. Uma requisição filtrada recebe os mesmos campos de qualquer outra, então uma chamada pode devolver os números mais recentes de alguns posts conhecidos.

The filters parameter
filters={"video_ids":["6995316737801538821","8015388216995316737"]}

Quais limites se aplicam?

A Accounts API permite 40 chamadas por minuto para cada conta autorizada neste endpoint, e as chamadas à Accounts API de um app somam 600 por minuto no nível Basic e 1.000 acima dele. Os campos descritivos são em tempo real, as contagens geralmente atrasam de 24 a 48 horas, e os dados de um post deixam de ser atualizados 365 dias após a publicação.

Como a easyCoexistence lista os vídeos?

Com list_social_posts, que recebe account_id e um limit opcional, de 1 a 20 para TikTok. Ele retorna a primeira página do TikTok: os posts mais recentes com item_id, create_time, caption, share_url, thumbnail_url, video_views, likes, comments e shares, além de cursor e has_more. Páginas seguintes e outros campos vêm do seu próprio código, com o token e o business_id de get_social_credentials:

The next page from your own code
GET https://business-api.tiktok.com/open_api/v1.3/business/video/list/
  ?business_id=<BUSINESS_ID>
  &fields=["item_id","media_type","caption","embed_url"]
  &cursor=1793404800000
  &max_count=20
Access-Token: <ACCESS_TOKEN>

Erros comuns

  • Pedir campos sem item_id. A referência do TikTok alerta que uma requisição com vários campos sem ele pode falhar.
  • Parar quando uma página vem curta. O TikTok pode retornar menos de max_count posts enquanto has_more ainda é true, então siga has_more.
  • Guardar thumbnail_url para depois. É um link temporário que expira no horário do parâmetro x-expires, então busque um novo quando precisar.
  • Procurar posts privados na lista. O endpoint retorna somente posts públicos.
Fazendo isso com o EasyCoexistence

De US$ 9 a US$ 0.75 por conexão por mês, caindo conforme você adiciona conexões, com 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

Quantos vídeos do TikTok a API consegue listar de uma vez?

Até 20 por página em /business/video/list/. max_count define o tamanho da página e assume 10 por padrão; siga o cursor para obter mais.

A API do TikTok também lista posts de foto?

Sim. /business/video/list/ retorna posts públicos de vídeo, foto e texto, e media_type diferencia VIDEO de PHOTO.

A lista de vídeos do TikTok inclui posts só para anúncios?

Sim. /business/video/list/ também retorna vídeos Only show in ads, que rodam como anúncios sem aparecer no perfil, e is_ad indica se um post está sendo usado em anúncio.

Por que um post do TikTok não aparece na lista da API?

O endpoint lista posts públicos, e o TikTok deixa de fora posts filtrados por violações, como direitos autorais de música.

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