API de Analytics de Links: Puxe Estatísticas de Cliques Com uma Chave de API

A API de analytics de links da Elido é um único endpoint, GET /v1/workspaces/{workspace_id}/analytics/{report} em https://api.elido.app, autenticado com uma chave de API do espaço de trabalho. Ela fornece 15 relatórios: série temporal de cliques, um resumo de engajamento, links principais, um feed de cliques recentes paginado por cursor e detalhamentos por país, referenciador, dispositivo, navegador, host e destino. As datas usam por padrão os últimos 30 dias, link_id restringe qualquer relatório a um link curto, e a exportação CSV, funis, coortes e LTV ficam no painel.

Essa é a resposta completa se você só precisava da URL. O restante deste guia é o que eu gostaria que toda página de API de analytics de cliques dissesse logo de início: os parâmetros exatos, o JSON que você recebe, onde o intervalo de datas funciona discretamente diferente do que você presumiria e um script de 30 linhas que publica os números de ontem no Slack toda manhã.

A maioria das pessoas que puxa dados de cliques está fechando um ciclo que começa com marcação de campanha, então, se seus links ainda não carregam UTMs consistentes, resolva isso primeiro com rastreamento UTM de ponta a ponta. Entradas limpas fazem as estatísticas valerem a pena.

O Que a API de Analytics de Links Retorna

Todo relatório fica sob o mesmo caminho, e o nome do relatório é o último segmento. Nomes com uma barra (links/top, clicks/recent, breakdown/country) entram sem codificação. Peça qualquer coisa fora da lista permitida e você recebe um 404 com unknown analytics report.

Repare na última linha. Os relatórios de região e cidade envolvem suas linhas em points, não em items, porque cada linha carrega um país mais uma região ou cidade em vez de uma única chave. Já vi um analisador genérico engasgar exatamente uma vez com isso. Uma vez basta.

O mesmo conjunto de relatórios sustenta a API e SDKs, a ferramenta de analytics do servidor MCP e a operação Get Analytics no nó n8n, então o que você aprende aqui se transfere.

Autenticação com uma Chave de API do Espaço de Trabalho

As chaves de API começam com elido_ e pertencem a exatamente um espaço de trabalho. Envie a chave como um token bearer:

curl -s "https://api.elido.app/v1/workspaces/4821/analytics/summary" \
  -H "Authorization: Bearer $ELIDO_API_KEY"

O roteador verifica duas coisas antes de qualquer consulta rodar: que a chave pertence ao espaço de trabalho 4821 e que ela tem analytics.view. Toda função integrada tem essa permissão, incluindo Viewer. Então crie uma chave Viewer para trabalhos de relatório. Um cron de relatórios não tem por que conseguir excluir links, e uma chave Viewer não consegue. Uma chave sem acesso recebe 403.

link_id também não amplia acesso. O ID do espaço de trabalho no caminho é o que foi verificado, então um ID de link emprestado do espaço de trabalho de outra pessoa corresponde a zero linhas e retorna uma lista vazia. Essa é a falha certa: sem graça, e nada vaza.

Parâmetros de Consulta para Estatísticas de Cliques: Datas, Fuso Horário, Filtros

Seis parâmetros cobrem quase toda chamada de API de estatísticas de links curtos que você vai fazer:

• from e to, como YYYY-MM-DD. Deixe ambos de fora e você recebe os 30 dias até agora. Defina apenas to, e from usa por padrão 30 dias antes dele.
• link_id para limitar qualquer relatório a um link, e host para limitar a um domínio de redirecionamento, útil quando um espaço de trabalho usa vários domínios com marca.
• interval para timeseries, como hour ou day (o padrão). Qualquer outra coisa faz a requisição falhar.
• limit para detalhamentos e listas de principais itens, de 1 a 200, padrão 50. links/top é o caso estranho: retorna 10 a menos que você peça mais.

Aqui está o detalhe que pega. As duas datas são lidas como meia-noite UTC, e a janela inclui from, mas para antes de to. Para todo o dia 21 de setembro, envie from=2026-09-21&to=2026-09-22. Envie to=2026-09-21 e você não recebe nada daquele dia.

Fuso horário é o outro ponto. Passe tz como um nome de fuso horário IANA, ou defina um cabeçalho X-User-TZ, e timeseries corta seus intervalos horários ou diários no horário local. Apenas os intervalos se movem. A janela from/to ainda é UTC, então um "ontem" em Berlim precisa de uma janela um pouco mais ampla, que o script abaixo trata. Um erro de digitação como Europe/Berln retorna 400 com unknown IANA timezone, o que é melhor do que um gráfico silenciosamente errado.

curl -s -G "https://api.elido.app/v1/workspaces/4821/analytics/timeseries" \
  -H "Authorization: Bearer $ELIDO_API_KEY" \
  --data-urlencode "from=2026-09-01" \
  --data-urlencode "to=2026-09-22" \
  --data-urlencode "interval=day" \
  --data-urlencode "tz=Europe/Berlin" \
  --data-urlencode "link_id=918273"

Formatos de Resposta Nos Quais Você Pode Programar

Um ponto de série temporal carrega ts, um timestamp RFC 3339 para o início do intervalo, e count. Intervalos com zero clique simplesmente não aparecem, então preencha as lacunas por conta própria antes de montar o gráfico, ou um domingo parado some do eixo x.

{
  "items": [
    { "ts": "2026-09-19T00:00:00Z", "count": 412 },
    { "ts": "2026-09-21T00:00:00Z", "count": 388 }
  ]
}

Detalhamentos retornam {"items": [{"key": "DE", "count": 1204}, ...]}, ordenados por contagem. O resumo é um objeto plano:

{
  "total_clicks": 5310,
  "unique_visitors": 3987,
  "returning_visitors": 611,
  "avg_clicks_per_visitor": 1.33,
  "bounce_rate": 0.85
}

Duas definições importam. Visitantes únicos são contados por endereço IP distinto na janela, então um escritório atrás de uma única conexão conta uma vez. E bounce_rate é uma fração, não uma porcentagem: a parcela de visitantes únicos que clicaram apenas uma vez na janela. Isso não diz nada sobre o que aconteceu na sua landing page, que é por isso que esses números nunca batem com sessões do GA4 (o post cliques versus sessões do GA4 percorre essa diferença). Todo número passa por filtro de bots antes de chegar a você, as mesmas contagens que você vê em analytics de links da Elido.

Paginando Cliques Recentes Com um Cursor

clicks/recent é o relatório da API de rastreamento de links que retorna cliques individuais, os mais novos primeiro. Cada linha tem ts, link_id, slug, host, referer, country_code, device, browser, destination, user_agent e ip. O tamanho da página vai de 1 a 500, padrão 100.

Quando uma página volta cheia, a resposta carrega um next_cursor. Passe-o como ?cursor= para obter a próxima página, mais antiga; null significa que você chegou ao fim da janela.

O cursor aponta para o timestamp e o ID do link da última linha. Dois cliques no mesmo link no mesmo milissegundo podem empatar no limite de uma página, e o pior caso é uma linha duplicada, nunca uma ignorada. Remova duplicatas usando a linha completa quando armazenar. É raro, mas uma inserção de dez linhas é melhor do que explicar um erro de off-by-one para a equipe financeira.

Essas linhas incluem endereços IP e user agents, então são dados pessoais. Se você estiver copiando isso para um data warehouse, mantenha na UE e defina um período de retenção; o guia de residência de dados na UE para equipes de marketing cobre o raciocínio. Para a maioria dos relatórios, você nem precisa das linhas brutas, e um agregado diário é melhor para todos.

Um Script de Relatório Diário de Cliques para Slack ou uma Planilha

Aqui está o trabalho que a maioria das pessoas realmente quer: toda manhã, publicar os cliques de ontem e os cinco links principais em um canal. Ele usa apenas a biblioteca padrão do Python e um webhook de entrada do Slack.

import datetime as dt, json, os, urllib.parse, urllib.request
from zoneinfo import ZoneInfo

BASE = "https://api.elido.app/v1/workspaces/{ws}/analytics/{report}"
WS, KEY = os.environ["ELIDO_WORKSPACE_ID"], os.environ["ELIDO_API_KEY"]
TZ = ZoneInfo("Europe/Berlin")

def report(name, **params):
    url = BASE.format(ws=WS, report=name) + "?" + urllib.parse.urlencode(params)
    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {KEY}"})
    with urllib.request.urlopen(req, timeout=20) as r:
        return json.load(r)

day = dt.datetime.now(TZ).date() - dt.timedelta(days=1)
# UTC window one day wider on each side, then keep only local hours of `day`
window = {"from": day - dt.timedelta(days=1), "to": day + dt.timedelta(days=2)}
hours = report("timeseries", interval="hour", tz="Europe/Berlin", **window)["items"]
total = sum(p["count"] for p in hours
            if dt.datetime.fromisoformat(p["ts"]).astimezone(TZ).date() == day)

top = report("links/top", limit=5, **{"from": day, "to": day + dt.timedelta(days=1)})
lines = [f"• {l['slug']}: {l['count']}" for l in top["items"]]
text = f"Clicks on {day} (Berlin): {total}\nTop links (UTC day):\n" + "\n".join(lines)

body = json.dumps({"text": text}).encode()
urllib.request.urlopen(urllib.request.Request(
    os.environ["SLACK_WEBHOOK_URL"], data=body,
    headers={"Content-Type": "application/json"}))

Rode pelo cron às 07:00 locais. O truque horário é o que faz o total ser um dia real de Berlim em vez de um dia UTC; links/top não tem tz, então seu ranking continua no dia UTC, e a mensagem diz isso.

Quer uma planilha? As mesmas duas chamadas funcionam no Google Apps Script com UrlFetchApp e um gatilho diário, acrescentando uma linha por dia. Esse também é o caminho mais barato para um painel do Looker Studio.

Se você ainda está colando números de capturas de tela toda segunda-feira, entregue uma chave Viewer para um script e recupere suas manhãs.

O Que Fica Apenas no Painel

O acesso por chave de API é somente leitura e deliberadamente mais estreita do que o painel. Estes recursos não são acessíveis com uma chave:

• A exportação CSV de cliques (clicks.csv). O botão Baixar CSV do painel é o caminho para arquivos em massa.
• Funis, coortes, o relatório de LTV, os mapas de calor de tempo e geografia e a visualização de qualidade de tráfego.

Se tudo de que você precisa é um arquivo chegando em algum lugar em uma agenda, os relatórios por email agendados do painel fazem isso sem código. Para uma extração completa, do tipo que se faz ao encerrar a conta, veja o que você consegue exportar de uma conta de links curtos e como verificar se está completo. E uma chamada combinada "tudo para um link" ainda não existe, então um painel por link significa uma requisição por relatório. O guia rápido dos SDKs cobre como executar essas chamadas em paralelo e aplicar backoff quando você atingir os limites de taxa.

Consulta da API de Analytics de Cliques versus Webhooks para Tempo Real

Versão honesta: hoje, dados de cliques existem apenas por consulta. Webhooks da Elido enviam eventos de link e domínio, assinados e com novas tentativas, mas um evento click.created por clique está no roteiro e ainda não é emitido. Qualquer coisa em tempo real sobre cliques significa consultar clicks/recent.

Isso dói menos do que parece. Consulte a cada um ou dois minutos, pare assim que alcançar uma linha que você já armazenou, e a carga continua minúscula, porque um minuto parado é uma página pequena. Quando click.created for lançado, o manipulador que processa uma linha não vai se importar se ela veio de uma página ou de um envio. As vantagens e desvantagens em geral estão explicadas em webhooks versus polling para rastreamento de cliques, e se você está decidindo quais desses números merecem um relatório, o que medir em analytics de links curtos é a leitura mais curta.

Minha opinião: comece pelo resumo diário. Quase toda equipe que me pede cliques em tempo real fica satisfeita com os números de ontem entregues antes do café.

Leia o guia principal → Como rastrear campanhas UTM de ponta a ponta

Relacionados no Blog

• Guia rápido da API e SDKs de encurtador de URLs - chaves, SDKs, limites de taxa e a chamada de criação.
• Nó n8n para encurtador de URLs - os mesmos relatórios de analytics dentro de um fluxo de trabalho n8n.
• Webhooks versus polling para rastreamento de cliques - como escolher o padrão de integração.
• Analytics de links no Looker Studio - transformando a coleta diária em um painel.
• Conecte a Elido ao Claude e ao Cursor com MCP - pedindo estatísticas de cliques em linguagem natural.