Primeiros passos

A API de Analytics do VTurb dá acesso programático aos dados de analytics da sua conta VTurb, para você:

• Consultar dados em tempo real e históricos
• Montar seus próprios relatórios e gráficos
• Levar os dados de analytics para as suas aplicações
• Automatizar pipelines de dados e decisões do seu negócio

Como começar

1. Crie uma conta, caso ainda não tenha.
2. Gere uma API key no seu painel.
3. Envie a chave em toda requisição, junto com a versão da API e um User-Agent, como descrito em Autenticação.
4. Escolha os dados de que precisa entre os endpoints listados no menu lateral.

URL base

https://analytics.vturb.com

Requisições e respostas são JSON. As consultas são requisições POST com um corpo JSON; algumas buscas, como GET /players/list e GET /quota/usage, são GET.

Datas e fusos horários

Salvo indicação do endpoint, as datas são enviadas no formato YYYY-MM-DD HH:MM:SS e lidas no fuso horário informado em timezone, um nome IANA como America/Sao_Paulo. Sem timezone, as datas são lidas em UTC.

{
  "start_date": "2026-09-01 00:00:00",
  "timezone": "America/Sao_Paulo"
}

Cada consulta só enxerga os players e os dados da empresa à qual a sua API key pertence.

Respostas

• Um parâmetro ausente ou inválido recebe 400, com um error que diz qual é.
• Na maioria das consultas, um player_id que não é da sua conta recebe 200 com zeros ou uma lista vazia, e não um erro. Quando todos os números voltarem zerados, confira o ID com o GET /players/list. /headlines/stats_by_player, /turbo/stats_by_player e /smart_autoplays/stats_by_player respondem 400 nesse caso.
• Os resultados ficam em cache e são atualizados em segundo plano, então a atividade dos últimos minutos pode ainda não aparecer.

Limites

A sua empresa tem uma cota de consultas por janela de tempo, definida pelo seu plano e compartilhada por todas as API keys dela:

O GET /quota/usage devolve os limites da sua empresa e quanto de cada um já foi usado. Uma única requisição pode contar como mais de uma consulta.

Quando a cota acaba, a API responde 429 Too Many Requests, com details indicando qual limite foi atingido e quando ele é renovado:

{
  "error": "Query quota exceeded for this API key. Please retry in a few moments or contact support at [email protected] if this persists.",
  "code": 201,
  "details": {
    "limit_kind": "queries",
    "used": 60,
    "limit": 60,
    "remaining": 0,
    "interval_seconds": 60,
    "resets_at": "2026-04-27T12:35:00Z"
  }
}

limit_kind é o limite que acabou, como queries ou read_bytes, os dados lidos pelas consultas. Espere até resets_at antes de tentar de novo, ou um pouco, quando details não vier. Se a sua integração precisa de um limite maior, fale com o suporte.

Suporte

Os exemplos de código de cada endpoint estão na página dele. Para qualquer outra dúvida, fale com o nosso suporte em help.vturb.com.