Como consulto meus dados de analytics programaticamente (Stats API)?

A Stats API é uma interface de consulta pública e com limite de taxa que permite buscar seus dados de analytics do Zenovay via HTTP. Use-a para criar dashboards personalizados, incorporar métricas ao vivo em ferramentas de BI ou migrar scripts do Plausible.

O que você pode consultar

Endpoint	O que retorna
GET /stats/aggregate	Totais de um período (visitantes, visualizações de página, taxa de rejeição, duração média da sessão).
GET /stats/timeseries	Um ponto de dado por dia, hora ou mês no período.
GET /stats/breakdown	Principais páginas, principais países, principais navegadores — qualquer dimensão única, ordenada por visitantes.

Referência completa, tabelas de parâmetros e exemplos: docs.zenovay.com/api/external-api (procure a seção "Stats API").

A especificação OpenAPI 3.1 ao vivo está disponível em /api/external/v1/openapi.json — importe no Postman, Insomnia ou use com um gerador de código.

Requisitos do plano

A Stats API está disponível nos planos Pro, Scale e Enterprise. O plano gratuito não pode criar ou usar chaves de API — as chamadas retornam um erro 403 API_PAID_PLAN_REQUIRED. Faça upgrade em Configurações → Faturamento.

Limites de taxa por nível

Plano	Limite de taxa (por minuto, alvo)	Cota mensal de requisições
Gratuito	10	1.000
Pro	30	10.000
Scale	60	100.000
Enterprise	120	1.000.000

Quando você excede o limite de taxa do seu nível, a API retorna 429 Too Many Requests com um cabeçalho Retry-After informando quantos segundos aguardar.

Como o limite de taxa é aplicado. O limite por minuto é um alvo, não um teto rígido. Usamos o limite de taxa de borda do Cloudflare, que é por data center com uma pequena margem de burst — portanto, um cliente contínuo pode ver transitoriamente 1,5–3× o número informado antes de ser limitado, especialmente se as requisições se distribuírem por regiões. O limite rígido é a cota mensal de requisições, que é aplicada atomicamente contra sua conta independentemente de onde as requisições se originam. Planeje cargas de trabalho sensíveis à capacidade com base na cota mensal; trate o número por minuto como um alvo de suavização.

Primeiros passos

1. Obtenha uma chave de API (Pro+) — veja Como obtenho uma chave de API?. As chaves começam com zv_.
2. Encontre o UUID do seu site — abra o website no seu painel Zenovay. O UUID está na URL: app.zenovay.com/domains/<UUID>.
3. Faça sua primeira chamada:

curl -G "https://api.zenovay.com/api/external/v1/stats/aggregate" \
  -H "X-API-Key: zv_YOUR_KEY" \
  --data-urlencode "site_id=YOUR_SITE_UUID" \
  --data-urlencode "period=7d" \
  --data-urlencode "metrics=visitors,pageviews"

Você deve receber algo como:

{
  "success": true,
  "data": {
    "results": {
      "visitors":  { "value": 12453 },
      "pageviews": { "value": 38219 }
    },
    "meta": { "period": "7d", "period_start": "...", "period_end": "..." }
  }
}

Casos de uso comuns

• Dashboards personalizados — busque métricas agregadas no Notion, Coda, Retool ou uma ferramenta de BI interna a cada hora.
• Migração do Plausible — o formato de parâmetros (site_id, period, date, metrics, filters, property) é intencionalmente compatível com o Plausible. A maioria dos scripts de migração funciona após substituir a URL base e remapear site_id de um domínio para o UUID do Zenovay.
• Embeds — exiba contagens de visitantes ao vivo na sua página de status ou site de marketing (use um proxy no servidor; nunca exponha sua chave de API no código do cliente).
• Relatórios agendados — busque dados de detalhamento uma vez por dia e envie para o Slack ou e-mail.

Filtros

Você pode limitar qualquer consulta a um subconjunto de visitantes com filtros no estilo Plausible:

# Apenas visitantes dos EUA
--data-urlencode "filters=country==US"

# Visitantes dos EUA + Canadá usando Chrome
--data-urlencode "filters=country==US,CA;browser==Chrome"

# Todos exceto páginas /admin
--data-urlencode "filters=page!=/admin"

Chaves de filtro permitidas: country, browser, device, os, source, utm_source, utm_medium, utm_campaign, page.

Limitação do V1: Quando você fornece filters, apenas a métrica visitors é calculada no V1; outras métricas retornam null com um sinalizador meta.note. Suporte completo a filtros em todas as métricas está no V2. As consultas sem filtro suportam todas as métricas hoje.

Solução de problemas

Sintoma	Causa	Correção
401 UNAUTHORIZED "Missing API key"	Sem cabeçalho X-API-Key ou Authorization: Bearer	Adicione o cabeçalho. Gere uma chave em Configurações → Conta → Segurança e acesso se não tiver uma.
401 UNAUTHORIZED "Invalid API key"	A chave foi revogada, tem um erro de digitação ou não começa com zv_	Copie novamente de Configurações → Conta → Segurança e acesso.
403 FORBIDDEN "requires a Pro plan"	Sua equipe está no plano Gratuito	Faça upgrade em Configurações → Faturamento.
403 FORBIDDEN "does not have access"	A chave de API foi limitada a um único site, mas site_id não corresponde	Crie uma chave de acesso completo ou faça a chamada com o site_id correto.
404 NOT_FOUND "Website not found"	UUID site_id errado	Verifique na URL do painel.
400 MISSING_*	Parâmetro de consulta obrigatório ausente	Adicione site_id, period e metrics (sempre obrigatórios).
400 INVALID_METRIC	Nome de métrica desconhecido	Use visitors, pageviews, visit_duration, bounce_rate ou events.
400 INTERVAL_PERIOD_MISMATCH	interval=hour com period diferente de day	Use period=day com interval=hour, ou use interval=day para períodos mais longos.
429 Too Many Requests	Limite de taxa por nível atingido	Respeite o cabeçalho Retry-After. Faça upgrade se atingir regularmente esse limite.

Migrando do Plausible

O formato de parâmetros é intencionalmente próximo ao da Stats API v1 do Plausible. Diferenças:

Plausible	Zenovay	Notas
site_id=mysite.com	site_id=<UUID>	O Plausible usa uma string de domínio; o Zenovay usa um UUID. Mapeie uma vez via GET /websites.
period, date	period, date	Mesma lista de valores + custom:YYYY-MM-DD,YYYY-MM-DD.
metrics	metrics	visitors, pageviews, bounce_rate, visit_duration mapeiam 1:1.
filters (formato de string v1)	filters	Mesmo formato key==value;key!=value.
filters (array JSON v2)	(V2 da Stats API do Zenovay)	Virá mais tarde.

Próximos passos

• Referência completa da Stats API (docs) — cada parâmetro, cada endpoint, cada código de erro.
• Especificação OpenAPI 3.1 — para geração de código e ferramentas de teste de API.
• Autenticação — cabeçalhos Bearer vs X-API-Key, rotação de chaves.
• Visão geral da API — todos os outros endpoints públicos do Zenovay (insights, anomalias, retenção, LTV, consulta em linguagem natural).