Un contrato de request, toda familia de informes.

Todos los paths tienen alcance de un proyecto — /projects/{project_id}/… — autenticados por clave y detrás de la flag reporting_api. Las fechas son ISO (YYYY-MM-DD); el grano de la ventana es day, week o month.

El 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[] es un WHERE preagregación: define qué respuestas se cuentan antes de sumar nada. Campos y operadores son conjuntos cerrados:

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

having[] es un HAVING posagregación sobre las medidas computadas — el mismo conjunto cerrado que acepta order_by:

visibility · share_of_voice · avg_position · sentiment · mention_count · responses_with_brand

Un campo está deliberadamente ausente: no existe filtro de marca. La marca reportada se elige después de la agregación, así que el Share of Voice nunca puede leer 1.0 bajo un filtro de marca — la cifra queda honesta por construcción.

La respuesta

Cada razón llega con sus componentes aditivos — mention_count, responses_with_brand y el response_count de la ventana — para que puedas reagregar correctamente: suma los componentes, divide una vez. Los deltas comparan contra la ventana anterior del mismo tamaño.

{
  "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 }
    }
  ]
}

En planes sin una columna premium el valor vuelve null y el id de la columna aparece en gated_columns — la forma de la respuesta nunca cambia con el plan.

Familias de informes

Los bodies varían solo donde el recurso lo exige: los informes de fuentes añaden un grano y un bloque gap opcional; el feed de respuestas añade filtros de presentación. Todo lo demás es el contrato de arriba.

Endpoint	Qué devuelve
POST /reports/brands	La tabla de marcas: Visibilidad, Share of Voice, posición y sentimiento por marca, con deltas de la ventana anterior.
POST /reports/timeseries	Series diarias, semanales o mensuales de las métricas de marca, más la serie de citas del dominio propio.
POST /reports/matrix	El pivot de visibilidad marca × motor, cada motor con su propio denominador.
POST /reports/rankings	La cuadrícula motor × posición en la respuesta: qué marca ocupó más cada slot.
POST /reports/prompts	Métricas por prompt para cada prompt rastreado, con una franja de resumen.
POST /reports/paired	Los dos lados de una comparación de dos ventanas, para slope charts.
POST /reports/rank-weekly	El rango ordinal de cada marca, por semana ISO.
POST /reports/slot-distribution	Cuántas veces cada marca ocupó cada slot — la distribución que una posición media esconde.
POST /reports/engine-composition	Share of Voice por marca dentro de cada motor, denominadores por motor.
POST /reports/coverage · /reports/coverage-disclosure	Qué se recolectó — conteos de respuestas por estado y motor — y cuánto del mercado cubre el conjunto rastreado.
POST /reports/absent	Los prompts que corrieron y nunca nombraron tu marca.
POST /reports/prompt-leaders · /prompt-brands · /prompt-series	Quién lidera cada prompt y por cuánto, la cuota de cada marca por prompt y tu propia tendencia semanal por prompt.
POST /reports/chats	El feed paginado de respuestas recolectadas.
GET /reports/chats/{chat_id}	Una respuesta, descompuesta: mensajes, features, fan-outs, fuentes y menciones.
POST /reports/domains · /reports/urls	Analítica de fuentes en grano de dominio, host o URL; añade el bloque gap para la variante de gap.
POST /reports/source-brands · /reports/gap-field	Qué marcas nombraron las respuestas que citan cada fuente, y el gap score descompuesto en sus dos conteos.
POST /reports/fanouts · /rollups · /coverage · /tree	Las búsquedas que los motores corrieron debajo de las respuestas: la tabla, los rollups de KPI, la cobertura y el árbol de un prompt.
GET /overview · /channels/freshness · /reports/brand-perception · /reports/sources/{url_id}	La franja de overview, las marcas de frescura por motor, los temas de percepción más recientes y el contenido rastreado de una fuente.

Export CSV

Cinco informes también exportan como CSV — endpoints GET cuyos parámetros de query reflejan los bodies de los POST, detrás de la flag csv_export, respetando los mismos filtros y orden.

Endpoint	Qué devuelve
GET /reports/brands/export	La tabla de marcas.
GET /reports/prompts/export	La tabla por prompt.
GET /reports/domains/export	El informe de dominios — o la lista de gap, cuando los parámetros de gap están presentes.
GET /reports/urls/export	El informe de URLs, con la misma variante de gap.
GET /reports/fanouts/export	Fan-out queries, marcas en las búsquedas o frases comunes — una superficie por petición.