Um contrato de request, toda família de relatório.

Todos os paths têm escopo de um projeto — /projects/{project_id}/… — autenticados por chave e atrás da flag reporting_api. Datas são ISO (YYYY-MM-DD); o grão da janela é day, week ou month.

O request

POST https://app.bementioned.ai/api/v1/projects/{project_id}/reports/brands

{
  "window": { "start": "2026-07-01", "end": "2026-07-31", "grain": "day" },
  "filters": [
    { "field": "country_code", "op": "in", "values": ["US"] }
  ],
  "having": [
    { "measure": "visibility", "op": "gte", "value": 0.25 }
  ],
  "order_by": "share_of_voice",
  "limit": 100,
  "offset": 0
}

filters[] é um WHERE pré-agregação: molda quais respostas são contadas antes de qualquer soma. Campos e operadores são conjuntos fechados:

model_channel_id · country_code · topic_id · prompt_id · tag_id · in · not_in · gt · gte · lt · lte

having[] é um HAVING pós-agregação sobre as medidas computadas — o mesmo conjunto fechado que order_by aceita:

visibility · share_of_voice · avg_position · sentiment · mention_count · responses_with_brand

Um campo está deliberadamente ausente: não existe filtro de marca. A marca reportada é escolhida depois da agregação, então o Share of Voice nunca pode ler 1.0 sob um filtro de marca — o número fica honesto por construção.

A resposta

Cada razão vem com seus componentes aditivos — mention_count, responses_with_brand e o response_count da janela — para você re-agregar corretamente: some os componentes, divida uma vez. Deltas comparam com a janela anterior de mesmo tamanho.

{
  "start": "2026-07-01",
  "end": "2026-07-31",
  "response_count": 372,
  "all_brand_mention_count": 941,
  "gated_columns": [],
  "brands": [
    {
      "brand_id": 7, "name": "Your Brand", "role": "you",
      "visibility": 0.42, "share_of_voice": 0.19,
      "avg_position": 2.4, "sentiment": 0.61,
      "mention_count": 158, "responses_with_brand": 156,
      "delta": { "visibility": 0.03, "share_of_voice": -0.01,
                 "avg_position": 0.2, "sentiment": 0.0 }
    }
  ]
}

Em planos sem uma coluna premium o valor volta null e o id da coluna aparece em gated_columns — a forma da resposta nunca muda com o plano.

Famílias de relatório

Os bodies variam só onde o recurso exige: os relatórios de fontes acrescentam um grão e um bloco gap opcional; o feed de respostas acrescenta filtros de exibição. Todo o resto é o contrato acima.

Endpoint	O que retorna
POST /reports/brands	A tabela de marcas: Visibilidade, Share of Voice, posição e sentimento por marca, com deltas da janela anterior.
POST /reports/timeseries	Séries diárias, semanais ou mensais das métricas de marca, mais a série de citações do próprio domínio.
POST /reports/matrix	O pivot de visibilidade marca × motor, cada motor com o próprio denominador.
POST /reports/rankings	A grade motor × posição na resposta: qual marca mais ocupou cada slot.
POST /reports/prompts	Métricas por prompt para cada prompt acompanhado, com uma faixa de resumo.
POST /reports/paired	Os dois lados de uma comparação de duas janelas, para slope charts.
POST /reports/rank-weekly	O rank ordinal de cada marca, por semana ISO.
POST /reports/slot-distribution	Quantas vezes cada marca ocupou cada slot — a distribuição que uma posição média esconde.
POST /reports/engine-composition	Share of Voice por marca dentro de cada motor, denominadores por motor.
POST /reports/coverage · /reports/coverage-disclosure	O que foi coletado — contagens de resposta por status e motor — e quanto do mercado o conjunto acompanhado cobre.
POST /reports/absent	Os prompts que rodaram e nunca nomearam a sua marca.
POST /reports/prompt-leaders · /prompt-brands · /prompt-series	Quem lidera cada prompt e por quanto, a participação de cada marca por prompt e a sua própria tendência semanal por prompt.
POST /reports/chats	O feed paginado de respostas coletadas.
GET /reports/chats/{chat_id}	Uma resposta, decomposta: mensagens, features, fan-outs, fontes e menções.
POST /reports/domains · /reports/urls	Analytics de fontes no grão de domínio, host ou URL; acrescente o bloco gap para a variante de gap.
POST /reports/source-brands · /reports/gap-field	Quais marcas as respostas que citam cada fonte nomearam, e o gap score decomposto nas suas duas contagens.
POST /reports/fanouts · /rollups · /coverage · /tree	As buscas que os motores rodaram por baixo das respostas: a tabela, os rollups de KPI, a cobertura e a árvore de um prompt.
GET /overview · /channels/freshness · /reports/brand-perception · /reports/sources/{url_id}	A faixa de overview, os marcos de frescor por motor, os temas de percepção mais recentes e o conteúdo rastreado de uma fonte.

Export CSV

Cinco relatórios também exportam como CSV — endpoints GET cujos parâmetros de query espelham os bodies dos POSTs, atrás da flag csv_export, honrando os mesmos filtros e ordenação.

Endpoint	O que retorna
GET /reports/brands/export	A tabela de marcas.
GET /reports/prompts/export	A tabela por prompt.
GET /reports/domains/export	O relatório de domínios — ou a lista de gap, quando os parâmetros de gap estão presentes.
GET /reports/urls/export	O relatório de URLs, com a mesma variante de gap.
GET /reports/fanouts/export	Fan-out queries, marcas nas buscas ou frases comuns — uma superfície por requisição.