API de medições só de leitura

Leve os seus dados de visibilidade em IA para os seus painéis, folhas de cálculo ou relatórios de agência. JSON ou CSV, uma chave por integração e apenas os dados do seu espaço de trabalho.

Autenticação

Crie uma chave em Conta, Chaves de API (apenas proprietários do espaço de trabalho). Envie-a como token Bearer. A chave completa é mostrada uma vez; guardamos apenas um hash. As chaves revogadas deixam de funcionar no pedido seguinte.

curl -H "Authorization: Bearer aeo_YOUR_KEY" \
  "https://YOUR-AEODA-DOMAIN/api/v1/brands/BRAND_ID/scores?from=2026-09-01&limit=50"

# CSV
curl -H "Authorization: Bearer aeo_YOUR_KEY" -o scores.csv \
  "https://YOUR-AEODA-DOMAIN/api/v1/brands/BRAND_ID/scores?format=csv&delimiter=semicolon"

Planos

A API está incluída no Pro e no Agency; a exportação CSV, a partir do Starter. Em caso de downgrade, as chaves existentes respondem 403 até o espaço de trabalho voltar a fazer upgrade.

Em caso de downgrade, as chaves ficam suspensas e respondem 403; voltam a funcionar assim que o espaço de trabalho faz upgrade. As chaves não são eliminadas.

Endpoints

Todos os endpoints são GET e só de leitura. URL base: o seu domínio aeoda.

Endpoint	Devolve
GET /api/v1/brands	As suas marcas (id, nome, domínio, mercado).
GET /api/v1/brands/{brandId}/scores	Histórico de pontuação: data, motor, pontuação, intervalo de confiança, taxa de menção.
GET /api/v1/brands/{brandId}/answers	Respostas: prompt, motor, mencionada ou não, posição, sentimento, concorrentes, texto.
GET /api/v1/brands/{brandId}/sources	Fontes citadas: domínio, URL, número de respostas, própria ou concorrente.
GET /api/v1/brands/{brandId}/competitors	Comparação com concorrentes: marca, pontuação, share of voice.
GET /api/v1/brands/{brandId}/recommendations	Plano de ação: título, prioridade, esforço, estado.

Parâmetros de consulta

from e to: datas como YYYY-MM-DD (por omissão, últimos 30 dias, limitados pelo histórico do seu plano). limit: de 1 a 1000 (por omissão 100). cursor: o valor nextCursor da página anterior. format: json (por omissão) ou csv. delimiter: comma ou semicolon (CSV). lang: idioma dos títulos das recomendações. Parâmetros desconhecidos devolvem 400.

Exemplo

{
  "data": [
    {
      "brand": "Northwind Coffee",
      "date": "2026-10-01T09:00:00.000Z",
      "engine": "all",
      "score": 55,
      "ci_low": 40,
      "ci_high": 70,
      "mention_rate": 25,
      "sov": 31.5,
      "avg_position": 2.4
    }
  ],
  "nextCursor": "eyJ0IjoiMjAyNi0xMC0wMSAwOTowMDowMCswMCIsImlkIjoiLi4uIn0",
  "range": { "from": "2026-09-01", "to": "2026-10-18" }
}

Formato CSV

O CSV é UTF-8 com marca de ordem de bytes para o Excel abrir bem os acentos. As células de texto que começam por = + - @ recebem um apóstrofo para evitar injeção de fórmulas. As respostas CSV são enviadas em fluxo e limitadas a 100 000 linhas: se atingir o limite (413), reduza o intervalo de datas.

Limites de utilização e paginação

Cada chave permite 60 pedidos por minuto. As respostas incluem x-ratelimit-limit e x-ratelimit-remaining; um 429 inclui retry-after. As listas JSON são paginadas com nextCursor (null na última página).

format=csv tem o seu próprio limite, mais baixo: 6 transferências por hora por chave, e uma resposta é limitada a 50 MB (uma última linha "# truncated" indica um ficheiro cortado).

Erros

401Chave em falta, malformada ou revogada.
403O plano do espaço de trabalho não inclui a API.
404A marca não existe no seu espaço de trabalho.
413Limite de linhas CSV excedido: use um intervalo de datas mais curto.
429Limite de utilização atingido: aguarde os segundos de retry-after.