Analytics

Leia o tráfego do site dono da chave de API. Os números vêm do pixel próprio (first-party) do Canverly: sem cookies e com filtro de bots — todo contador desta página conta apenas humanos.

Método	Caminho	Escopo
GET	/v1/analytics/summary	analytics:read
GET	/v1/analytics/posts	analytics:read

• URL base: https://api.canverly.com
• Autenticação: Authorization: Bearer ck_… — escopo analytics:read
• Limite de requisição: 60 req/min por chave

Cuidado

Estas rotas precisam de uma chave secreta ck_. A chave pública de leitura pk_ não pode carregar analytics:read, então nunca consegue alcançá-las — não coloque um painel de tráfego no navegador com uma chave pública. Veja Autenticação.

Não existe parâmetro de site. O site é derivado da chave, então uma chave só lê o tráfego do próprio site.

Escolhendo a janela

As duas rotas aceitam os mesmos três parâmetros de janela.

Parâmetro	Tipo	Padrão	Observações
from	string (YYYY-MM-DD, UTC)	—	Início da janela. Quando presente, prevalece sobre days.
to	string (YYYY-MM-DD, UTC)	hoje	Fim da janela, inclusivo — to=2026-08-30 inclui o dia 30 de agosto inteiro.
days	integer	30	Janela predefinida dos últimos N dias (1–365). Ignorado quando from é informado.

Precedência: um from válido seleciona o intervalo explícito (com to, ou até agora); caso contrário, vale a predefinição de days. Um intervalo explícito é limitado a 366 dias.

Nota

A leitura da janela é tolerante: um days que não seja inteiro, ou que esteja fora de 1–365, volta em silêncio para a predefinição de 30 dias, e um from inválido faz o mesmo — nenhum dos dois gera erro. Sempre leia os campos from, to e days devolvidos na resposta para confirmar qual janela foi de fato aplicada, em vez de supor que sua entrada foi aceita.

GET /v1/analytics/summary

Totais principais, uma série por dia e os caminhos mais vistos na janela.

curl "https://api.canverly.com/v1/analytics/summary?days=7" \
  -H "Authorization: Bearer ck_live_xxx"

Intervalo explícito:

curl "https://api.canverly.com/v1/analytics/summary?from=2026-08-01&to=2026-08-30" \
  -H "Authorization: Bearer ck_live_xxx"

200 OK

{
  "from": "2026-08-01",
  "to": "2026-08-30",
  "days": 30,
  "totals": { "views": 18420, "visitors": 11207, "sessions": 12958 },
  "timeseries": [
    { "date": "2026-08-01", "views": 612, "visitors": 401 },
    { "date": "2026-08-02", "views": 588, "visitors": 377 }
  ],
  "top_paths": [
    { "key": "/como-fazer-x", "views": 2140 },
    { "key": "/precos", "views": 1877 }
  ]
}

Campo	Tipo	Observações
from	string	Primeiro dia da janela (UTC, inclusivo).
to	string	Último dia da janela (UTC, inclusivo).
days	integer	Extensão da janela em dias.
totals.views	integer	Visualizações de página.
totals.visitors	integer	Visitantes distintos.
totals.sessions	integer	Sessões distintas.
timeseries[].date	string	Um dia UTC, com lacunas preenchidas (um dia sem tráfego aparece com zeros).
timeseries[].views	integer	Visualizações de página naquele dia.
timeseries[].visitors	integer	Visitantes distintos naquele dia.
top_paths[].key	string	Caminho da URL, ex.: /como-fazer-x.
top_paths[].views	integer	Visualizações de página daquele caminho na janela.

Nota

A resposta é repassada do serviço de analytics e hoje traz blocos extras de detalhamento além dos campos acima (realtime, engagement, referrers, geo, devices…). Eles não fazem parte do contrato documentado — não dependa deles; leia os campos da tabela e ignore o resto.

GET /v1/analytics/posts

O conteúdo mais visto do site, paginado.

Cuidado

A unidade aqui é um caminho de URL, não um id de post. Esta rota é uma projeção do top_paths do resumo, paginada na borda — o serviço de analytics não expõe um endpoint separado por post, e os eventos são contados por caminho. Você recebe path + views; para relacionar uma linha a um post, compare-a você mesmo com o slug/URL desse post. Por consequência, total é o tamanho da lista top_paths do resumo (um ranking top-N, hoje limitado na origem a 25 linhas), não o número de posts do site.

Parâmetros

Os três parâmetros de janela acima, mais:

Parâmetro	Tipo	Padrão	Observações
limit	integer	50	1–200. Fora do intervalo ou não numérico é um 400 — nunca ajustado em silêncio.
offset	integer	0	Precisa ser ≥ 0; qualquer outro valor é um 400.

curl "https://api.canverly.com/v1/analytics/posts?days=30&limit=10" \
  -H "Authorization: Bearer ck_live_xxx"

Segunda página:

curl "https://api.canverly.com/v1/analytics/posts?days=30&limit=10&offset=10" \
  -H "Authorization: Bearer ck_live_xxx"

200 OK

{
  "items": [
    { "path": "/como-fazer-x", "views": 2140 },
    { "path": "/precos", "views": 1877 }
  ],
  "total": 25,
  "limit": 10,
  "offset": 0
}

Campo	Tipo	Observações
items[].path	string	Caminho da URL.
items[].views	integer	Visualizações de página na janela.
total	integer	Linhas disponíveis no ranking antes da paginação.
limit	integer	Tamanho de página aplicado.
offset	integer	Offset aplicado.

Você chegou ao fim quando offset + items.length >= total.

Erros

Envelope: { "error": { "code", "message" } }. Tabela completa em Erros e limites de requisição.

Status	error.code	Quando
400	bad_request	Só em /v1/analytics/posts — limit fora de 1–200 ou não numérico, ou um offset negativo/não numérico. A message indica o parâmetro problemático.
401	unauthorized	Chave ausente, inválida ou revogada.
403	forbidden	A chave não tem analytics:read.
429	rate_limited	Acima de 60 req/min — respeite Retry-After.
5xx	upstream	Erro transitório na origem; tente de novo com backoff.

Observações práticas

• Faça cache do resumo. Agregados de tráfego mudam devagar; uma chamada por renderização do painel (ou a cada poucos minutos) é suficiente, e as duas rotas dividem o mesmo limite de 60 req/min com o resto da API.
• /posts custa o mesmo que /summary. Ela é calculada a partir da mesma leitura na origem, então pedir as duas são duas leituras na origem — se você já tem o resumo, já tem o top_paths.
• Zero linhas é uma resposta válida. Um site recém-criado, ou uma janela anterior à instalação do pixel, retorna totais zerados e arrays vazios, não um 404.