Dos tuberías: registros hacia fuera, logs hacia dentro.

Conector de BI

POST /bi/records devuelve registros planos de un rango de fechas, de una de dos tablas — mentions o sources — agrupados por las dimensiones que pases. Detrás de la flag bi_connector.

POST https://app.bementioned.ai/api/v1/projects/{project_id}/bi/records

{
  "start_date": "2026-07-01",
  "end_date": "2026-07-31",
  "table": "mentions",
  "dimensions": ["week", "brand_id", "model_channel_id"],
  "limit": 10000,
  "offset": 0
}

Las dimensiones son un conjunto cerrado, con como máximo un grano de tiempo por petición:

date · week · month · model_channel_id · country_code · prompt_id · topic_id · tag_id · brand_id · domain · url · source_type

Las filas llevan solo componentes aditivos — conteos, y sumas junto a sus conteos — y ninguna razón, a propósito: suma los componentes en tu herramienta de BI y divide una vez, y el agregado es exacto en cualquier agrupación.

Un aviso que vale leer dos veces: scope_response_count es el denominador de la fila y se repite idéntico entre filas hermanas de un mismo alcance — nunca lo sumes entre marcas, dominios o URLs. Y source_type siempre va separado y se refleja en cada fila: api y web_scrape nunca se mezclan.

Webhook de ingest — agent analytics

Envía los access logs de tu CDN o servidor y el producto los convierte en visitas de agent analytics: qué crawlers de IA leyeron qué páginas. El token se acuña al crear una fuente de ingest en la app — prefijo bmi_, mostrado una vez, rotable.

curl -X POST https://app.bementioned.ai/api/v1/ingest/agent-logs \
  -H "X-Ingest-Token: bmi_your_token_here" \
  --data-binary @access-log-batch.csv

El endpoint guarda el payload verbatim y responde 202 con un recibo — líneas conservadas, y líneas descartadas por motivo:

{
  "batch_id": 118,
  "line_count": 5000,
  "kept_count": 4816,
  "dropped": { "no_ua_match": 121, "ip_spoof": 12, "malformed": 51 }
}

Límites: 25 MiB por lote, 600 lotes por minuto por fuente, y un bucket estricto de credencial inválida. 401 para un token ausente o revocado, 403 para una fuente pausada, 413 por encima del tope de tamaño, 429 con Retry-After.

Esta superficie no lleva plan flag ni el límite de serving: la captura nunca se detiene por un motivo de plan. Las líneas se interpretan por el formato declarado de la fuente; las alegaciones de bot no verificables se descartan y se contabilizan en el recibo.