Encontre o ID de um player

Quase toda consulta recebe um player_id: o ID de um player da sua conta VTurb, com 24 caracteres hexadecimais. O GET /players/list devolve esse ID, junto com a duração do vídeo do player e o tempo de pitch dele, que as consultas de retenção e de pitch usam.

Liste os seus players

A requisição só precisa dos cabeçalhos de autenticação:

curl 'https://analytics.vturb.com/players/list' \
  -H "X-Api-Token: $VTURB_API_TOKEN" \
  -H 'X-Api-Version: v1' \
  -H 'User-Agent: minha-integracao/1.0'

[
  {
    "id": "64a5c8072e6fd10009828db2",
    "name": "Black Friday VSL",
    "pitch_time": 1260,
    "duration": 2340,
    "created_at": "2025-07-18 10:00:00"
  }
]

Players excluídos não são listados, nem os players cujo vídeo foi excluído.

Busque pelo nome

Com muitos players, filtre pelo nome em vez de percorrer todos eles:

curl 'https://analytics.vturb.com/players/list?name=black%20friday&name_match=starts_with' \
  -H "X-Api-Token: $VTURB_API_TOKEN" \
  -H 'X-Api-Version: v1' \
  -H 'User-Agent: minha-integracao/1.0'

• name perde os espaços das pontas e, depois disso, precisa ter de 3 a 128 caracteres. Ele ignora maiúsculas e minúsculas, inclusive em letras acentuadas (É casa com é, não com e). %, _ e \ são tratados como literais.
• name_match define o modo da busca: contains (o padrão), starts_with, ends_with ou exact. Ele exige name.

Filtre pela data de criação

start_date e end_date mantêm só os players criados nesse intervalo, com as datas lidas em timezone (UTC quando você não o envia):

curl -G 'https://analytics.vturb.com/players/list' \
  --data-urlencode 'start_date=2026-09-01 00:00:00' \
  --data-urlencode 'end_date=2026-09-30 23:59:59' \
  --data-urlencode 'timezone=America/Sao_Paulo' \
  -H "X-Api-Token: $VTURB_API_TOKEN" \
  -H 'X-Api-Version: v1' \
  -H 'User-Agent: minha-integracao/1.0'

As duas datas são opcionais, e cada uma é escrita no formato YYYY-MM-DD HH:MM:SS.

Guarde os IDs

O ID de um player não muda, então busque-o uma vez e guarde-o com o seu relatório ou a sua integração. duration e pitch_time acompanham a configuração atual do player: leia-os de novo quando o vídeo ou o pitch mudar.

A seguir: monte um relatório diário ou meça a retenção e o pitch do player que você encontrou.