REST API

A API do Statsdot disponibiliza os mesmos dados que o seu painel, em formato JSON, e permite-lhe gerir sites, objetivos, a sua equipa e tokens. Cada pedido requer um token de acesso pessoal.

Autenticação

Crie um token na página API e MCP da sua conta. Escolha read only (apenas leitura) para scripts e relatórios, ou read and write (leitura e escrita) se o token também precisar de efetuar alterações. Copie o token quando este for apresentado: não será exibido novamente.

Envie-o no cabeçalho Authorization de cada pedido:

curl https://statsdot.com/api/v1/sites \
  -H "Authorization: Bearer 12|your-token" \
  -H "Accept: application/json"

Um token tem acesso ao que o seu utilizador vê: os seus próprios sites e os sites das equipas a que pertence, com a sua função nessas equipas. Um leitor pode ler um site da equipa, um gestor também pode alterá-lo, e apenas o proprietário pode eliminá-lo.

URL base e formato

• URL base: https://statsdot.com/api/v1
• Os pedidos e respostas são em JSON. As respostas bem-sucedidas envolvem o resultado em data.
• As horas seguem a norma ISO 8601 em UTC.

Intervalos e filtros

Cada endpoint de estatísticas aceita os mesmos parâmetros de consulta que o painel:

Parâmetro	Valores
range	today, 7d, 30d (predefinição), 12m, ou um intervalo personalizado 2026-09-01~2026-09-30 (dias UTC completos, no máximo dois anos)
filters[page]	Apenas acessos neste caminho de página
filters[entry]	Visitas que começaram nesta página
filters[source]	Domínio de referência, por exemplo google.com; vazio significa direto
filters[utm_source], filters[utm_medium], filters[utm_campaign]	Etiquetas de campanha da página de destino
filters[country]	Código de país ISO, por exemplo ES
filters[device]	Desktop, Mobile ou Tablet
filters[browser], filters[os]	Conforme apresentado no painel
filters[event]	Visitas que enviaram este evento
filters[goal]	Visitas que atingiram este ID de objetivo

Os visitantes num intervalo são visitantes-dia: o Statsdot conta um visitante uma vez por dia, porque o código de visitante muda diariamente.

Estatísticas

Método e caminho	O que devolve
GET /sites/{site}/stats/overview	Visitantes, visualizações de página, taxa de rejeição e duração da visita (segundos), com o período anterior de igual duração e a variação percentual
GET /sites/{site}/stats/timeseries	Visitantes e visualizações de página por dia, ou por mês para intervalos superiores a 90 dias
GET /sites/{site}/stats/breakdown/{breakdown}	Valores principais de uma dimensão por visitantes. breakdown é um de pages, entry_pages, exit_pages, referrers, utm_source, utm_medium, utm_campaign, countries, devices, browsers, operating_systems, events, event_labels (com event=Name). limit de 1 a 100, predefinição 10
GET /sites/{site}/stats/goals	Cada objetivo com os visitantes que o atingiram, conversões e taxa de conversão
GET /sites/{site}/stats/realtime	Visitantes nos últimos cinco minutos
GET /sites/{site}/stats/bots	Pedidos de crawlers de IA no período: total, por crawler e as páginas que mais leram (crawler=openai-gptbot filtra as páginas). Requer rastreamento de crawlers de IA; os filtros não se aplicam

Exemplo:

curl "https://statsdot.com/api/v1/sites/42/stats/breakdown/referrers?range=7d&limit=5" \
  -H "Authorization: Bearer 12|your-token"

{
  "data": {
    "from": "2026-10-11T00:00:00+00:00",
    "to": "2026-10-17T10:15:00+00:00",
    "filters": {},
    "breakdown": "referrers",
    "rows": [
      { "value": "google.com", "visitors": 312 },
      { "value": "", "visitors": 145 }
    ]
  }
}

Conta e sites

Método e caminho	O que faz
GET /account	O seu plano, eventos utilizados este mês e incluídos, limites e as capacidades do token
GET /sites	Sites que pode ver, com a sua função, definições e snippet de rastreamento
GET /sites/{site}	Um site
POST /sites	Adicionar um site: {"domain": "example.com"}. Adicione account_id para o adicionar a uma conta de equipa que gere. Aplicam-se os limites do plano dessa conta
PATCH /sites/{site}	Alterar weekly_report, public_live, shared (ligação pública de apenas leitura), alert_traffic, alert_silence ou main_goal_id (um objetivo do site, ou null)
DELETE /sites/{site}	Eliminar um site que possui e todas as suas estatísticas

Objetivos

Método e caminho	O que faz
GET /sites/{site}/goals	Os objetivos de um site
POST /sites/{site}/goals	{"type": "page", "value": "/thanks"} ou {"type": "event", "value": "Signup"}
DELETE /sites/{site}/goals/{goal}	Eliminar um objetivo; as visitas permanecem

Funis

Método e caminho	O que faz
GET /sites/{site}/funnels	Os funis de um site
POST /sites/{site}/funnels	{"name": "Sign-up", "steps": [{"type": "page", "value": "/"}, {"type": "page", "value": "/pricing"}, {"type": "event", "value": "Signup"}]}: 2 a 8 passos, no máximo 10 funis por site
DELETE /sites/{site}/funnels/{funnel}	Eliminar um funil
GET /sites/{site}/stats/funnels/{funnel}	Visitantes em cada passo por ordem dentro do mesmo dia, com a percentagem em relação ao anterior e ao primeiro passo; aplicam-se intervalos e filtros

Notas

Método e caminho	O que faz
GET /sites/{site}/notes	Notas no gráfico; from e to (YYYY-MM-DD) restringem a lista
POST /sites/{site}/notes	{"date": "2026-10-17", "text": "Newsletter sent"}: um dia passado ou presente, até 200 caracteres
DELETE /sites/{site}/notes/{note}	Eliminar uma nota

Equipa

Método e caminho	O que faz
GET /team	Pessoas convidadas para a sua conta, o limite do plano e as equipas a que pertence
POST /team	Convidar: {"email": "[email protected]", "role": "viewer"} (viewer ou manager). O e-mail de convite é enviado; a resposta inclui a ligação de convite
PATCH /team/{member}	Alterar a função
DELETE /team/{member}	Remover uma pessoa ou um convite pendente

Tokens

Método e caminho	O que faz
GET /tokens	Os seus tokens, com as suas capacidades e última utilização
POST /tokens	{"name": "Reports", "abilities": ["read"]}. O token simples está na resposta, uma única vez. Um token de apenas leitura não pode criar um token de escrita
DELETE /tokens/{token}	Revogar um token

Erros

Os erros utilizam o estado HTTP e um corpo com um código estável:

{ "error": { "code": "account_blocked", "message": "The account that owns this site has no active plan." } }

Estado	Quando
401	Token em falta ou inválido
402	A conta não tem um plano ativo, excedeu o seu plano ou atingiu um limite
403	O token é de apenas leitura e o pedido altera algo
404	O site, objetivo ou membro não existe ou não está disponível para este token
422	Parâmetros inválidos, por exemplo um intervalo ou breakdown desconhecido
429	Demasiados pedidos

Limites

• 120 pedidos por minuto por token.
• No máximo 25 tokens por conta.
• A API está incluída em todos os planos e no período experimental.