Conceitos essenciais
As regras comuns a todos os endpoints: filtros, definições de métricas, saída em JSON e CSV, códigos de erro e gestão de versões.
Filtros e parâmetros comuns
project_idobrigatório para todos os endpoints com âmbito de projeto.metricsoumetric: CSV dementions, 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_sentimentgranularity:day|week|month(as semanas começam à segunda-feira)- Janela temporal:
range(dias) oufrometo(ISO8601). Se enviarto,fromé obrigatório. Predefinições comfrom/to: semfrom= há 30 dias (início do dia); semto= 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çãotrue): definafalsepara 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. Paraweek/monthcalculamos 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 comovisibility): 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: pontuação ponderada pela posição, que tem em conta a proeminência das menções. Cada resposta que menciona o ator soma 100 ÷ posição pontos (posição 1 = 100, posição 2 = 50, posição 3 = 33,33, etc.), e os pontos são divididos pelos dias com dados, ou seja, os dias com respostas com os mesmos filtros, pelo que a pontuação corresponde a um dia de monitorização médio: não é uma percentagem, não tem limite máximo de 100 e não cresce com a duração do intervalo. Os pontos dos concorrentes são divididos pelos dias com dados do projeto, pelo que as respetivas pontuações são comparáveis com as suas. •day: os pontos do dia. •week/month: os pontos do período divididos pelos respetivos dias com dados, repetidos em cada dia do período; se um período não tiver qualquer resposta, «transportamos» o último valor de período (sticky). •/metrics/summary: os pontos do intervalo divididos pelos respetivos dias com dados, o mesmo número que a Visão geral apresenta. - 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 devolvemnull. •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 devolvenullquando 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: calcula uma única pontuação com base nas contagens somadas em todo o intervalo, a mesma pontuação que a aplicação apresenta para os mesmos filtros, e devolvenullquando o intervalo não tem sentimentos classificados.
Em /metrics/summary, total é uma soma para as métricas de contagem e os pontos do intervalo divididos pelos respetivos dias com dados para ai_visibility_score. As taxas, as posições e o sentimento (visibility, citation_rate, avg_position, avg_mention_position, net_sentiment e as percentagens de sentimento) são calculados a partir dos totais de todo o intervalo, o mesmo número que a aplicação apresenta para os mesmos filtros, e nunca como média dos valores dos períodos.
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.
outputomitido (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 maiscolumns(nomes das colunas por ordem),rows(um objeto plano por linha) erow_count.output=csv: as mesmas linhas quetext/csv, comcolumnscomo 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/timeseries|queries|pages, /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-PageeX-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
outputcomERR_INVALID_PARAM, em vez de o ignorar.
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_INSUFFICIENT_SCOPE | 403 | Foi usada uma chave ou um token OAuth só de leitura numa operação de escrita |
| ERR_INSUFFICIENT_PERMISSION | 403 | O utilizador da chave não está autorizado a realizar esta ação (por exemplo, um membro da equipa sem a permissão necessária) |
| ERR_KEY_PROJECT_SCOPED | 403 | Foi usada uma chave limitada a determinados projetos numa operação que atua sobre toda a conta |
| ERR_PLAN_REQUIRED | 403 | O plano da conta não inclui este endpoint |
| ERR_INTEGRATION_UNAVAILABLE | 403 | Esta funcionalidade não está disponível para esta conta ou neste domínio |
| ERR_ACCOUNT_INACTIVE | 403 | A subscrição da conta terminou ou a conta está suspensa por falta de pagamento de uma renovação |
| ERR_SEARCH_CONSOLE_ACCESS_REVOKED | 403 | O Google revogou o acesso do projeto ao Search Console; volte a ligar a propriedade |
| ERR_CMS_ACCESS_REVOKED | 403 | O WordPress já não aceita a senha de aplicação guardada, ou o respetivo utilizador não pode escrever artigos; volte a ligar o site |
| ERR_WEB_ANALYTICS_ACCESS_REVOKED | 403 | O fornecedor de análise web recusou as credenciais guardadas; volte a ligá-lo |
| ERR_DRAFT_NOT_FOUND | 404 | Rascunho de projeto não encontrado ou criado por outro utilizador |
| ERR_PROJECT_NOT_FOUND | 404 | project_id não acessível por este utilizador |
| ERR_NOT_FOUND | 404 | Recurso não encontrado |
| ERR_SEARCH_CONSOLE_NOT_CONNECTED | 404 | O projeto não tem nenhuma propriedade do Google Search Console ligada |
| ERR_CMS_NOT_CONNECTED | 404 | O projeto não tem nenhum site WordPress ligado |
| ERR_AI_TRAFFIC_NOT_CONNECTED | 404 | O projeto não tem nenhum fornecedor de análise web ligado para o tráfego de IA |
| ERR_WEB_ANALYTICS_NOT_CONNECTED | 404 | O projeto não tem nenhum fornecedor de análise web ligado |
| ERR_AGENT_TRAFFIC_NOT_CONNECTED | 404 | O projeto não tem nenhuma origem de tráfego de agentes ligada |
| ERR_STALE_CONTENT | 409 | A tarefa do GEO Writer foi regenerada depois do result_version enviado com a edição; nada foi guardado |
| ERR_DRAFT_STATE | 422 | Rascunho de projeto expirado, já finalizado ou com um passo anterior em falta (a mensagem indica qual) |
| ERR_CMS_REJECTED | 422 | O WordPress recusou o pedido, o site passou a redirecionar para outro endereço ou já não é possível aceder-lhe de forma segura; tentar novamente não resolve |
| ERR_WEB_ANALYTICS_INVALID_QUERY | 422 | O fornecedor de análise web rejeitou a consulta (a mensagem inclui o erro de validação do fornecedor) |
| ERR_INVALID_RANGE | 422 | Intervalo de datas do Search Console com from posterior a to |
| 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) |
| ERR_RATE_LIMITED | 429 | Limite de pedidos excedido; aguarde o número de segundos indicado em Retry-After |
| ERR_GENERATION_FAILED | 502 | Uma geração por IA falhou; repita o pedido |
| ERR_SEARCH_CONSOLE_UPSTREAM | 503 | O Google Search Console está indisponível ou excedeu a quota; aguarde o número de segundos indicado em Retry-After |
| ERR_CMS_UPSTREAM | 503 | Não foi possível aceder ao site WordPress ou este demorou demasiado tempo; tente novamente mais tarde |
| ERR_WEB_ANALYTICS_UPSTREAM | 503 | O fornecedor de análise web está indisponível ou o projeto atingiu o limite de consultas em tempo real; aguarde o número de segundos indicado em Retry-After |
Estrutura do corpo do erro:
Casos típicos de 422:
invalid metrics: só são permitidosmentions, 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 serday|week|month.from/to must be ISO8601oufrom is required with to.range is requiredquando não são enviadosfromnemto.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, contando em conjunto as chamadas REST e MCP. Um cliente MCP com sessão iniciada através de OAuth tem o mesmo limite de 300 pedidos por minuto. Não existe qualquer quota mensal ou diária de pedidos; os limites por minuto são os únicos limites de pedidos. Contacte-nos se uma chave precisar de um limite por minuto mais elevado.
As operações de escrita (POST, PATCH, PUT e DELETE) contam também para um segundo limite de 60 pedidos por minuto por chave de API. O endpoint MCP e POST /web_analytics/query, que é só de leitura, estão isentos.
Todas as respostas a pedidos feitos com uma chave de API incluem os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset (o tempo Unix, em segundos, em que termina a janela atual de um minuto) referentes a esse limite por chave. O limite de escrita não tem cabeçalhos próprios.
Um pedido que exceda qualquer um dos limites recebe uma resposta HTTP 429 com o código de erro ERR_RATE_LIMITED. O cabeçalho Retry-After dessa resposta indica a duração da janela do limite em segundos (60), pelo que aguardar esse tempo basta sempre para que o limite seja reposto. Quando é excedido o limite por chave, a resposta 429 inclui também os três cabeçalhos X-RateLimit-*.
Os pedidos que utilizam as quotas do plano continuam a contar para essas quotas, por exemplo novos prompts (que também gastam parte das respostas de IA disponíveis no ciclo de monitorização), projetos, concorrentes por projeto, tarefas mensais do GEO Writer, execuções manuais de auditorias GEO e projetos de pitch mensais. GET /account indica quanto resta de cada uma.