Conceitos essenciais

As regras comuns a todos os endpoints: filtros, definições de métricas, saída em JSON e CSV, colocação em cache, códigos de erro e gestão de versões.

Filtros e parâmetros comuns

project_id obrigatório para todos os endpoints com âmbito de projeto.
metrics ou metric: CSV de mentions, citations, responses, mention_rate (or visibility), citation_rate, ai_visibility_score, avg_position, avg_mention_position, sentiment_very_positive, sentiment_positive, sentiment_neutral, sentiment_negative, sentiment_very_negative, net_sentiment
granularity: day|week|month (as semanas começam à segunda-feira)
Janela temporal: range (dias) ou from e to (ISO8601). Se enviar to, from é obrigatório. Predefinições com from/to: sem from = há 30 dias (início do dia); sem to = agora (fim do dia).
Filtros: model, collection_id (ID da etiqueta), prompt (ID do prompt), country_code, language_code, competitors (IDs em CSV)
include_project (predefinição true): defina false para excluir o seu projeto (devolve apenas os concorrentes).

Definições das métricas

Estas semânticas estão alinhadas 1:1 com a interface de Visão Geral.

Menções: somas diárias de mentions_count. Para week/month calculamos o TOTAL DO PERÍODO (segunda a domingo, no caso das semanas) e repetimos esse mesmo total em cada dia do período. Se o total de um período for 0, transportamos o último total de período diferente de zero (sticky).
citations: contagem ao nível da resposta que inclui citações visíveis e referências a fontes de fundo. Cada entidade é contabilizada, no máximo, uma vez por resposta. Segue as mesmas regras de total por período e de manutenção do último total não nulo que as menções.
responses: número total de execuções de prompts (chamadas à API de LLMs). Utiliza a contagem de execuções ao nível do projeto, independentemente da entidade. • day: soma diária. • week/month: total do período (sem propagação de valores anteriores; os dias com 0 execuções apresentam 0).
Taxa de menções mention_rate (também aceite como visibility): percentagem por ator, utilizando as execuções ao nível do projeto como denominador com os mesmos filtros (mentions_count / prompt_executions_count × 100). • day: calcular o rácio diário. • week/month: calcular o rácio de somas do período (Σ menções / Σ execuções) e repetir esse valor em cada dia do período. Se o denominador do período for 0, transportar o último valor não nulo.
citation_rate: percentagem de respostas que incluem uma citação visível ou de fundo para a entidade (citations_count / prompt_executions_count × 100). • day: rácio diário. • week/month: rácio entre as somas do período, mantendo o último valor não nulo, como em visibility.
AI Visibility Score ai_visibility_score: métrica de visibilidade ponderada pela posição, que tem em conta a proeminência das menções. Usa ponderação recíproca por posição (posição 1 = 100%, posição 2 = 50%, posição 3 = 33%, etc.). Pontuações mais altas indicam mais menções e melhor posicionamento. • day: calcula a pontuação ponderada diária dividida pelo número de execuções. • week/month: rácio entre as somas do período, mantendo o último valor não nulo, como em visibility.
avg_position: posição média das citações visíveis. As citações em segundo plano não têm posição visível e são excluídas. • day: média diária, excluindo valores nulos. • week/month: calcula a média do período, ignorando os valores nulos, e propaga depois o último valor conhecido para os dias sem dados, tal como na suavização do gráfico de Visão Geral.
avg_mention_position: posição média da marca quando é mencionada nas respostas de IA (posição 1 = primeira menção, posição 2 = segunda, etc.). Quanto mais baixa, melhor. • day: média diária, excluindo valores nulos. • week/month: média do período, mantendo o último valor não nulo nos dias sem dados.
Métricas de sentimento sentiment_very_positive,sentiment_positive,sentiment_neutral,sentiment_negative,sentiment_very_negative: para cada ator e dia, percentagem de sentimentos nessa categoria sobre todos os sentimentos desse ator. • day: rácio diário (bucket_count / total_sentiments * 100). Os dias sem sentimentos devolvem null. • week/month: calculamos um rácio de somas do período (Σ bucket / Σ total * 100) e repetimos essa percentagem em cada dia do período. Se o denominador do período for 0, transportamos o último valor não nulo (sticky), em consonância com a suavização da Visão Geral.
Pontuação de sentimento líquido net_sentiment: para cada ator e dia, a pontuação varia entre -100 e 100 e calcula-se como ((very_positive + positive) − (negative + very_negative)) / total_sentiments × 100, sendo total_sentiments a soma das contagens das cinco categorias de sentimento. O cálculo utiliza diretamente as contagens, sem arredondar primeiro as percentagens de cada categoria, e arredonda a pontuação resultante a duas casas decimais. • day: calcula a pontuação com base nas contagens desse dia e devolve null quando não há sentimentos classificados. • week/month: calcula uma pontuação por período com base nas contagens somadas nesse período; a API devolve um ponto por período. Se um período não tiver sentimentos classificados, a API mantém a última pontuação não nula. Na API REST, os períodos iniciais sem dados começam em 0. • /metrics/summary: apresenta a média dos pontos não nulos da série temporal de net_sentiment.

Em /metrics/summary, total é uma soma para as métricas de contagem e uma média para avg_position, avg_mention_position e net_sentiment.

Formatos de saída para ferramentas de BI

Os endpoints de leitura devolvem JSON aninhado por predefinição, o que é prático para código, mas ilegível para ferramentas de business intelligence. Indique o parâmetro opcional output para obter os mesmos dados numa tabela retangular que o Tableau, o Excel, o Google Sheets ou um carregador de armazém de dados podem consumir diretamente.

output omitido (predefinição): o JSON aninhado documentado para cada endpoint. Inalterado, pelo que as integrações existentes não são afetadas.
output=flat: os mesmos metadados mais columns (nomes das colunas por ordem), rows (um objeto plano por linha) e row_count.
output=csv: as mesmas linhas que text/csv, com columns como linha de cabeçalho.

Compatível com /metrics/timeseries, /metrics/summary, /metrics/sov, /metrics/prompt_summary, /metrics/top_sources, as séries /search_console/* e os endpoints /dimensions/* que devolvem listas. Os endpoints cujo payload não é uma única tabela (/metrics/agent_traffic, /metrics/ai_traffic, /search_console/summary, /dimensions/models, /dimensions/locales) rejeitam output, em vez de o ignorar.

/metrics/sov também aceita view=over_time (predefinição), view=current ou view=breakdown: o seu payload contém várias formas diferentes e uma tabela só pode conter uma de cada vez.

Colunas por endpoint

Endpoint	Columns
`/metrics/timeseries`	`date, actor_type, actor_id, actor_name, actor_domain, metric, value`
`/metrics/summary`	`actor_type, actor_id, actor_name, actor_domain, metric, aggregation, total, min, max, last`
`/metrics/sov`	`date, actor_type, actor_id, actor_name, actor_domain, share`
`/metrics/sov?view=current`	`actor_type, actor_id, actor_name, actor_domain, share`
`/metrics/sov?view=breakdown`	`rank, actor_type, actor_id, actor_name, actor_domain, share, others`
`/metrics/prompt_summary, /metrics/top_sources, /search_console/, /dimensions/`	The keys of the endpoint's own data rows

Exemplo

GET /api/v1/metrics/timeseries?project_id=1&range=30&metrics=mentions&output=csv

date,actor_type,actor_id,actor_name,actor_domain,metric,value
2025-01-01,project,1,My Brand,mybrand.com,mentions,10
2025-01-01,competitor,2,Competitor A,competitor.com,mentions,5

Notas:

Os erros são sempre devolvidos em JSON, nunca em CSV, para que uma falha nunca seja confundida com dados.
As percentagens mantêm-se na escala bruta de 0 a 100, exatamente como na resposta JSON.
As células de texto que começam com os sinais de igual, mais, menos ou arroba são escapadas para que as folhas de cálculo não as executem como fórmulas.
Os endpoints paginados também devolvem os metadados de paginação nos cabeçalhos de resposta X-Total-Count, X-Page e X-Per-Page, que um corpo CSV não pode transportar.
A saída flat está limitada a 200 000 linhas. Acima disso, reduza o intervalo de datas, peça menos métricas ou utilize granularity=week.
Os endpoints sem projeção flat rejeitam output com ERR_INVALID_PARAM, em vez de o ignorar.

Cache e GET condicional

Os endpoints de métricas (timeseries, summary, sov, top_sources) suportam GET condicional. Calculamos um ETag a partir da versão do projeto e de um hash dos parâmetros da sua consulta, e utilizamos o updated_at do projeto como Last-Modified.

Envie If-None-Match ou If-Modified-Since para receber 304 Not Modified quando nada mudou.

Erros

Os erros usam uma estrutura JSON consistente. Decida com base no campo code. O campo message contém os detalhes do erro quando disponíveis; caso contrário, contém um token predefinido como missing_authorization:

Código	HTTP	Significado
ERR_MISSING_AUTH	401	Cabeçalho Authorization ausente ou malformado
ERR_INVALID_API_KEY	401	Token não reconhecido
ERR_REVOKED_API_KEY	403	Chave revogada
ERR_PROJECT_NOT_FOUND	404	project_id não acessível por este utilizador
ERR_NOT_FOUND	404	Recurso não encontrado
ERR_INVALID_PARAM	422	A validação falhou (ver message)
ERR_LIMIT_REACHED	422	Limite de projetos, prompts, relatórios técnicos GEO ou recomendações atingido (a mensagem indica qual)
ERR_QUOTA_EXCEEDED	422	Limite de concorrentes, tarefas do GEO Writer ou subscrições de webhook atingido (a mensagem indica qual)

Estrutura do corpo do erro:

Casos típicos de 422:

invalid metrics: só são permitidos mentions, citations, responses, mention_rate (or visibility), citation_rate, ai_visibility_score, avg_position, avg_mention_position, sentiment_very_positive, sentiment_positive, sentiment_neutral, sentiment_negative, sentiment_very_negative, net_sentiment.
invalid granularity: tem de ser day|week|month.
from/to must be ISO8601 ou from is required with to.
range is required quando não são enviados from nem to.
unknown competitor ids: ...: IDs não encontrados no projeto.

Versionamento e limites de pedidos

Versão atual: v1. Futuras alterações incompatíveis irão atualizar o caminho (por exemplo /api/v2).

Limitação de pedidos: 300 pedidos por minuto por chave de API. Contacte-nos para quotas superiores.

Os endpoints de métricas suportam GET condicional (ETag/Last-Modified); consulte Cache e GET condicional.

Exemplos de código

Download: OpenAPI Swagger Postman

Perguntar à IA: Abrir no ChatGPT Abrir no Claude Ver como Markdown

Linguagem

Example with Filters

curl -X GET -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.llmpulse.ai/api/v1/metrics/timeseries?project_id=PROJECT_ID&metrics=mentions,visibility&granularity=day&range=30&model=gpt-4o&locale=en-US"

const response = await fetch("https://api.llmpulse.ai/api/v1/metrics/timeseries?project_id=PROJECT_ID&metrics=mentions,visibility&granularity=day&range=30&model=gpt-4o&locale=en-US", {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});
const data = await response.json();

import requests

response = requests.get(
    "https://api.llmpulse.ai/api/v1/metrics/timeseries?project_id=PROJECT_ID&metrics=mentions,visibility&granularity=day&range=30&model=gpt-4o&locale=en-US",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = response.json()

require 'httparty'

response = HTTParty.get(
  "https://api.llmpulse.ai/api/v1/metrics/timeseries?project_id=PROJECT_ID&metrics=mentions,visibility&granularity=day&range=30&model=gpt-4o&locale=en-US",
  headers: { "Authorization" => "Bearer YOUR_API_KEY" }
)
data = response.parsed_response

req, _ := http.NewRequest("GET", "https://api.llmpulse.ai/api/v1/metrics/timeseries?project_id=PROJECT_ID&metrics=mentions,visibility&granularity=day&range=30&model=gpt-4o&locale=en-US", nil)
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()

$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://api.llmpulse.ai/api/v1/metrics/timeseries?project_id=PROJECT_ID&metrics=mentions,visibility&granularity=day&range=30&model=gpt-4o&locale=en-US', [
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY']
]);
$data = json_decode($response->getBody(), true);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.llmpulse.ai/api/v1/metrics/timeseries?project_id=PROJECT_ID&metrics=mentions,visibility&granularity=day&range=30&model=gpt-4o&locale=en-US"))
    .header("Authorization", "Bearer YOUR_API_KEY")
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

Conditional GET Example

# Primeiro pedido
curl -i -H "Authorization: Bearer $KEY" \
  "https://api.llmpulse.ai/api/v1/metrics/summary?project_id=...&metrics=mentions&range=30" \
| grep -iE 'etag|last-modified'

# Pedido condicional subsequente
curl -i -H "Authorization: Bearer $KEY" \
  -H 'If-None-Match: "prev-etag-here"' \
  "https://api.llmpulse.ai/api/v1/metrics/summary?project_id=...&metrics=mentions&range=30"

Error Response Format

HTTP/1.1 401
{ "error": { "code": "ERR_MISSING_AUTH", "message": "missing_authorization" }, "request_id": "..." }

Error Body Example

{ "error": { "code": "ERR_INVALID_PARAM", "message": "range must be a positive integer" }, "request_id": "..." }