Documentación de la API

LLM Pulse API

Crea paneles, pipelines de ETL y automatizaciones con una API limpia y bien tipada.

LLM Pulse es una plataforma de analítica de visibilidad en IA que monitoriza cómo aparece tu marca en las respuestas generadas por IA de ChatGPT, Perplexity, Gemini y otros LLM. La API te da acceso programático a todos tus datos de visibilidad, incluidas las métricas de menciones de marca, fuentes de citación, análisis de sentimiento y Share of Voice. Úsala para crear paneles personalizados, automatizar informes o integrar el seguimiento de visibilidad en IA en tus herramientas actuales.

Autenticación

Envía tu clave en la cabecera Authorization como token Bearer. Rota o revoca la clave en Configuración → Claves de API.

Cabeceras ausentes o mal formadas devuelven 401 ERR_MISSING_AUTH. Las claves desconocidas devuelven 401 ERR_INVALID_API_KEY. Las claves revocadas devuelven 403 ERR_REVOKED_API_KEY.

Cada llamada se ejecuta en el contexto del usuario de la clave de API. Los proyectos deben pertenecer a ese usuario; de lo contrario, 404 ERR_PROJECT_NOT_FOUND.

Estos endpoints aceptan POST/PATCH/PUT/DELETE y requieren una clave de API con el ámbito read_write. Un token con el ámbito read recibe 403 ERR_INSUFFICIENT_SCOPE. Las escrituras comparten un límite de solicitudes más estricto (60/min por clave) además del tope global de 300/min por clave.

Inicio rápido

El flujo lógico es: listar recursos → (opcionalmente) obtener dimensiones → consultar métricas. La primera llamada a /dimensions/projects ya valida tu clave de API.

1. Lista tus proyectos: GET /dimensions/projects
2. (Opcional) Obtén las dimensiones del proyecto (competidores, modelos, locales, etiquetas)
3. Consulta métricas en /metrics/*

Comprobación de estado

GET/ping

La forma más económica de comprobar que una clave funciona y medir la latencia de ida y vuelta. Devuelve pong, el id del usuario autenticado y la hora del servidor. Pasa project_id para verificar también que la clave puede acceder a ese proyecto.

Cuenta y límites

GET/account

Plan, cadencia de monitorización, período de suscripción, cuánto se ha consumido de cada cuota (prompts, proyectos, competidores por proyecto, tareas mensuales de GEO Writer y miembros del equipo) y los límites de solicitudes de la API que se aplican a tu clave. Llámalo antes de cualquier operación que consuma cuota para poder informar de lo que queda en lugar de descubrir el tope al chocar con él. Los límites se resuelven a través del propietario de la cuenta, por lo que un miembro del equipo ve la capacidad que le corresponde. Una cuota ilimitada devuelve limit y remaining como null, con unlimited establecido en true.

• Parámetros: ninguno.

CLI y SDK oficiales

Usa la CLI nativa desde un terminal o añade un SDK con tipos a tu aplicación. Ambos se generan a partir del documento OpenAPI publicado y funcionan con las mismas claves de API y la misma URL base que se muestran en esta referencia.

Zona de pruebas de la API

curl -X GET "https://api.llmpulse.ai/api/v1/ping" -H "Authorization: Bearer YOUR_API_KEY"

La respuesta aparecerá aquí...

Filtros y parámetros comunes

• project_id obligatorio para todos los endpoints con ámbito de proyecto.
• metrics o metric: CSV con 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 (las semanas empiezan en lunes)
• Ventana de tiempo: o bien range (días) o from y to (ISO8601). Si envías to, from es obligatorio. Valores por defecto con from/to: si falta from = hace 30 días (inicio del día); si falta to = ahora (fin del día).
• Filtros: model, collection_id (ID de tag), prompt (ID de prompt), country_code, language_code, competitors (IDs en CSV)
• include_project (por defecto true): establece false para excluir tu proyecto (devuelve solo competidores).

Definición de métricas

Estas semánticas están alineadas 1:1 con la interfaz de Resumen.

• mentions: sumas diarias de mentions_count. Para week/month calculamos el TOTAL DEL PERÍODO (de lunes a domingo en las semanas) y repetimos ese mismo total para todos los días del período. Si el total de un período es 0, «arrastramos» el último total de período distinto de cero (arrastre persistente).
• citations: recuento a nivel de respuesta que incluye las citaciones visibles y las referencias a fuentes en segundo plano. Cada actor cuenta como máximo una vez por respuesta. Usa el mismo comportamiento de total del período y arrastre persistente que las menciones.
• responses: número total de ejecuciones de prompt (llamadas de API a los LLM). Usa el recuento de ejecuciones del proyecto, independientemente del actor. • day: suma diaria. • week/month: total del período (sin arrastre persistente; los días con 0 ejecuciones muestran 0).
• Tasa de mención mention_rate (también aceptado como visibility): porcentaje por actor, usando las ejecuciones del proyecto como denominador con los mismos filtros (mentions_count / prompt_executions_count × 100). • day: calcula la proporción diaria. • week/month: calcula la proporción de sumas del período (Σ menciones / Σ ejecuciones) y repite ese valor para todos los días del período. Si el denominador del período es 0, arrastra el último valor no nulo.
• citation_rate: porcentaje de respuestas que incluyen una citación visible o en segundo plano para el actor (citations_count / prompt_executions_count × 100). • day: proporción diaria. • week/month: proporción de sumas del período con arrastre persistente, igual que la visibilidad.
• AI Visibility Score ai_visibility_score: métrica de visibilidad ponderada por posición que tiene en cuenta la prominencia de la mención. Usa ponderación recíproca por posición (posición 1 = 100%, posición 2 = 50%, posición 3 = 33%, etc.). Las puntuaciones más altas indican tanto más menciones como mejor posicionamiento. • day: calcula la puntuación ponderada diaria / ejecuciones. • week/month: proporción de sumas del período con arrastre persistente, igual que la visibilidad.
• avg_position: posición media de las citaciones visibles. Las citaciones en segundo plano no tienen posición visible y quedan excluidas. • day: media diaria excluyendo los nulos. • week/month: media dentro del período (ignorando los nulos) y después se propaga (arrastra) el último valor conocido a los días sin datos, igual que el suavizado del gráfico de Resumen.
• avg_mention_position: posición media de la marca cuando aparece mencionada en las respuestas de IA (posición 1 = primera mención, posición 2 = segunda, etc.). Cuanto más baja, mejor. • day: media diaria excluyendo los nulos. • week/month: media dentro del período con arrastre persistente.
• Métricas de sentimiento sentiment_very_positive,sentiment_positive,sentiment_neutral,sentiment_negative,sentiment_very_negative: para cada actor y día, porcentaje de sentimientos de esa categoría sobre todos los sentimientos de ese actor. • day: proporción diaria (bucket_count / total_sentiments * 100). Los días sin sentimientos devuelven null. • week/month: calculamos una proporción de sumas del período (Σ bucket / Σ total * 100) y repetimos ese porcentaje para todos los días del período. Si el denominador del período es 0, arrastramos el último valor no nulo (arrastre persistente), igual que el suavizado del Resumen.
• Puntuación de sentimiento neto net_sentiment: para cada actor y día, calculamos una puntuación en [-100, 100]: ( (very_positive + positive) − (negative + very_negative) ) / total_sentiments × 100. • day: usamos los porcentajes diarios de cada categoría (las métricas sentiment_*) y calculamos net = (pos+very_pos) − (neg+very_neg). • week/month: la puntuación hereda las mismas semánticas de agregación y suavizado que las categorías de sentimiento, porque se calcula a partir de esas series.

En /metrics/summary, total es una suma para las métricas de recuento y una media para avg_position, avg_mention_position y net_sentiment.

Formatos de salida para herramientas de BI

Los endpoints de lectura devuelven JSON anidado por defecto, lo que resulta cómodo para el código pero ilegible para las herramientas de business intelligence. Pasa el parámetro opcional output para obtener los mismos datos como una tabla rectangular que Tableau, Excel, Google Sheets o un cargador de data warehouse puedan consumir directamente.

• output omitido (por defecto): el JSON anidado documentado para cada endpoint. Sin cambios, por lo que las integraciones existentes no se ven afectadas.
• output=flat: los mismos metadatos más columns (nombres de columna ordenados), rows (un objeto plano por fila) y row_count.
• output=csv: las mismas filas que text/csv, con columns como fila de encabezado.

Disponible en /metrics/timeseries, /metrics/summary, /metrics/sov, /metrics/prompt_summary, /metrics/top_sources, la serie /search_console/* y los endpoints /dimensions/* que devuelven listas. Los endpoints cuyo payload no es una única tabla (/metrics/agent_traffic, /metrics/ai_traffic, /search_console/summary, /dimensions/models, /dimensions/locales) rechazan output en lugar de ignorarlo.

/metrics/sov también acepta view=over_time (por defecto), view=current o view=breakdown: su payload contiene varias formas distintas y una tabla solo puede contener una a la vez.

Columnas por endpoint

Ejemplo

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:

• Los errores siempre se devuelven como JSON, nunca como CSV, por lo que un fallo nunca se confunde con datos.
• Los porcentajes se mantienen en la escala bruta de 0 a 100, exactamente igual que en la respuesta JSON.
• Las celdas de texto que empiezan por un signo igual, más, menos o arroba se escapan para que las hojas de cálculo no las ejecuten como fórmulas.
• Los endpoints paginados también devuelven sus metadatos de paginación en las cabeceras de respuesta X-Total-Count, X-Page y X-Per-Page, que un cuerpo CSV no puede transportar.
• La salida plana tiene un límite de 200.000 filas. A partir de ahí, reduce el rango de fechas, solicita menos métricas o usa granularity=week.
• Los endpoints sin proyección plana rechazan output con ERR_INVALID_PARAM en lugar de ignorarlo.

Caché y GET condicional

Los endpoints de métricas (timeseries, summary, sov, top_sources) admiten GET condicional. Calculamos un ETag a partir de la versión del proyecto y de un hash de tus parámetros de consulta, y usamos el updated_at del proyecto como Last-Modified.

Envía If-None-Match o If-Modified-Since para recibir 304 Not Modified cuando nada haya cambiado.

Errores

Los errores son uniformes y analizables por máquina:

Estructura del cuerpo de error:

Casos típicos de 422:

• invalid metrics: solo se permiten 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: debe ser day|week|month.
• from/to must be ISO8601, o from is required with to.
• range is required cuando no se envía ni from ni to.
• unknown competitor ids: ...: IDs no encontrados en el proyecto.

Versiones y límites de solicitudes

Versión actual: v1. Los futuros cambios incompatibles incrementarán la versión de la ruta (p. ej. /api/v2).

Límite de solicitudes: 300 solicitudes por minuto y clave de API. Contacta con nosotros para cuotas superiores.

Los endpoints de métricas admiten GET condicional (ETag/Last-Modified); consulta Caché y GET condicional.

Proyectos

Un proyecto es una marca monitorizada: su dominio, configuración regional, prompts y competidores. Casi todos los demás endpoints reciben un project_id, así que empieza aquí.

GET/dimensions/projects

Lista los proyectos del usuario autenticado (también sirve como comprobación de autenticación).

GET/dimensions/projects/:id

Obtén información detallada sobre un proyecto: nombres coincidentes, sector, modelo de negocio, recuento de prompts por enfoque de marca y data_coverage (los modelos, países e idiomas que realmente tienen datos), de modo que una sola llamada sustituye a las consultas independientes de modelos y locales.

GET/dimensions/models

Lista los modelos presentes en las métricas diarias del proyecto.

GET/dimensions/locales

Lista los países e idiomas presentes en las métricas diarias del proyecto.

POST/projects

Crea un proyecto completo en una sola llamada (modo rápido): proyecto, prompts (en cola para ejecución y categorización), competidores y suscripción al correo semanal. Idempotente cuando se proporciona external_identifier. El proyecto siempre pertenece al propietario de la cuenta.

• Cuerpo (JSON): website_url (obligatorio, URL HTTP(S) pública con un nombre de host DNS o una dirección IP pública; se rechazan las URL con credenciales, las direcciones IP privadas y especiales, localhost y los nombres de host internos), name (obligatorio), main_country (obligatorio), main_language (obligatorio), brand_name, description, industry (array), business_model, target_audience, brand_voice, goals, primary_products (array), matching_names (array), prompts (array, máx. 100), competitors (array de objetos {domain, brand_name, matching_names}), owned_media (objeto, Growth+), use_subdomain, weekly_email_subscribed, external_identifier (solo cuentas con embed habilitado; clave de idempotencia, [a-z0-9_-]{1,64}), execute_prompts_immediately (por defecto, true).

PATCH/projects/:id

Actualiza el perfil del proyecto (el Brand Book y el emparejamiento de marca), los mismos campos que en la configuración del proyecto. Los campos del Brand Book (description, industry, brand_voice, target_audience) alimentan a GEO Writer, las sugerencias de prompts y las recomendaciones. Cambiar matching_names relanza el emparejamiento de menciones/citaciones sobre el historial del proyecto en segundo plano (rematching: true; mientras tanto, las ediciones quedan bloqueadas); un cambio de brand_name solo se aplica a las ejecuciones futuras. Los campos desconocidos se rechazan.

• Cuerpo (JSON): envía solo los campos que quieras cambiar: brand_name, description, industry (una sola clave), business_model, target_audience, brand_voice, goals, primary_products (array de sustitución completa), matching_names (array de SUSTITUCIÓN COMPLETA; envía todas las variantes que quieras conservar).

Asistente de borradores de proyecto

Asistente de creación de proyectos en varios pasos con sugerencias de IA: POST /project_drafts inicia un borrador (devuelve el nombre, la descripción y el sector sugeridos para la URL), PATCH envía cada paso (details, prompts, competitors, owned_media) con una validación estricta del avance entre pasos y devuelve sugerencias para el siguiente paso, y POST /project_drafts/:id/finalize crea el proyecto real. Los borradores caducan tras 24h.

• La website_url inicial debe ser una URL HTTP(S) pública con un nombre de host DNS o una dirección IP pública. Se rechazan las URL con credenciales, las direcciones IP privadas y especiales, localhost y los nombres de host internos. Pasos: details (name obligatorio), prompts (máx. 100, sujeto a cuota), competitors (limitado por plan), owned_media (opcional, Growth+). Sugerencias por paso, con opción de desactivarlas mediante suggest=false; las URL frías pueden tardar hasta ~2 minutos, configura el timeout del cliente en 180s. Finalize es idempotente y vuelve a comprobar todos los requisitos.

Métricas

Datos agregados de visibilidad, Share of Voice, citaciones y posiciones de tu marca y sus competidores, listos para representar en gráficos. Todos los endpoints aceptan los filtros comunes y el parámetro output descrito en Conceptos básicos.

GET/metrics/timeseries

Devuelve series temporales de una o más métricas, agrupadas por actor (tu proyecto + los competidores seleccionados). Los valores semanales y mensuales siguen la semántica de períodos descrita más arriba. Los filtros opcionales prompt_type (intención de búsqueda) y brand_kind acotan cada métrica a una categoría de prompt.

GET/metrics/summary

Agrega por actor y métrica (total/min/max/last). Ideal para tarjetas KPI.

GET/metrics/prompt_summary

Devuelve métricas agregadas por prompt y paginadas (responses, mentions, citations, mention_rate, citation_rate, avg_mention_position, avg_position). Admite breakdown=model para añadir la dimensión de modelo de IA a cada fila, devolviendo métricas por prompt y por modelo. Parámetros: sort (responses, mentions, citations, mention_rate o visibility, citation_rate, avg_mention_position, avg_position), sort_dir (asc/desc), breakdown (model), page, per_page (máx. 100).

GET/metrics/sov

Share of Voice basado en menciones, alineado con el resumen.

• over_time: para cada fecha, SOV = (actor_mentions / sum_all_mentions) × 100. Si la suma diaria es 0, se arrastra el último valor (sticky).
• current: usa la fecha más reciente con total distinto de cero; si no hay ninguna, usa los totales de todo el rango.
• breakdown: los 4 principales actores + una fila agregada Others (y una lista detallada others).

GET/metrics/top_sources

Ordena los dominios de fuentes por número de respuestas y tasa media de mención (% de ejecuciones en las que apareció ese dominio).

• El conjunto de datos incluye fuentes no rechazadas vinculadas a ejecuciones de prompts dentro del período y los filtros actuales.
• total_responses: número de ejecuciones de prompt únicas que produjeron al menos una fuente en ese dominio.
• avg_mention_rate (también se devuelve como avg_visibility): (número de filas de fuentes del dominio / total de ejecuciones) × 100.
• Ordenación: sort=total_responses (por defecto), sort=avg_mention_rate o sort=avg_visibility.
• Paginación: page (>=1), per_page (por defecto 20, máximo 100).
• Filtra por dominio: query (LIKE sin distinguir mayúsculas), p. ej. query=github.

Competidores

Las marcas que monitorizas junto a la tuya. Los IDs de competidor devueltos aquí son los valores actor_id con los que informan los endpoints de métricas.

GET/dimensions/competitors

Lista los competidores del proyecto.

GET/dimensions/competitors/:id

Obtén información detallada sobre un competidor, incluidos los nombres coincidentes y los IDs de app store.

POST/competitors

Añade un competidor (brand_name + domain) a un proyecto. Respeta el tope máximo de competidores por plan.

PATCH/DELETE /competitors/:id

Actualiza un competidor (brand_name, matching_names, color; el domain es inmutable tras su creación) o elimínalo. Los cambios de nombre relanzan el emparejamiento de menciones/citaciones en segundo plano (processing: true durante unos minutos; mientras tanto, las ediciones quedan bloqueadas). La eliminación es irreversible y purga los datos del competidor en segundo plano.

Prompts

Las preguntas que lanzamos a los modelos de IA cada semana y los registros de ejecución que genera cada ejecución.

GET/dimensions/prompts

Lista los prompts de un proyecto.

GET/dimensions/prompt_executions

Lista las ejecuciones de prompt de un proyecto.

GET/dimensions/query_fan_outs

Las subconsultas que un modelo emitió realmente al responder a tus prompts monitorizados, útiles para descubrir la redacción que los modelos buscan en lugar de la redacción que escribiste tú. view=query (por defecto) devuelve una fila por subconsulta distinta con su recuento y su proporción sobre el total de apariciones; view=prompt devuelve una fila por prompt con el número de subconsultas distintas que generó. El fan-out lo reporta principalmente ChatGPT, así que un resultado vacío suele significar que los modelos consultados no lo exponen.

POST/prompts

Crea hasta 100 prompts por solicitud. Los prompts existentes (mismo texto + locale) se omiten.

DELETE/prompts/:id

Elimina un prompt. Es irreversible; el prompt desaparece de inmediato, libera un hueco de prompt y un trabajo en segundo plano purga su historial (ejecuciones, menciones, citaciones, sentimiento). Requiere una clave de API con permisos de escritura.

Colecciones y tags

Las colecciones (denominadas Tags en la aplicación) agrupan los prompts por tema, etapa del embudo o campaña, de modo que cualquier métrica pueda filtrarse por ellas. Un prompt puede pertenecer a varias.

GET/dimensions/collections

Lista las colecciones (Tags) que pertenecen al proyecto.

GET/dimensions/tags

Alias de /dimensions/collections. Devuelve el mismo payload, pero denominado tags para mantener la coherencia con la interfaz.

POST/collections

Crea una etiqueta (Collection) en un proyecto. Opcionalmente, adjunta prompts existentes en la misma llamada. El nombre de la etiqueta es único por proyecto y no distingue mayúsculas de minúsculas.

PATCH/DELETE /collections/:id

Cambia el nombre de una etiqueta, modifica su descripción o elimínala. Al eliminar una etiqueta, los prompts que contiene se conservan; solo desaparece la agrupación. La pertenencia de prompts se gestiona mediante POST /prompts/assign_tags.

• Cuerpo de PATCH: project_id (obligatorio), name y/o description. DELETE: project_id + :id en la URL.

POST/prompts/assign_tags

Adjunta etiquetas a prompts existentes de forma masiva e idempotente. Las etiquetas se pueden indicar por id o por nombre.

Respuestas (respuestas de IA)

Las respuestas de IA que hay detrás de cada métrica, con su texto completo, menciones, citaciones y análisis de sentimiento.

GET/answers

Enumera las respuestas de IA con su contenido. Devuelve resultados paginados con el texto de la respuesta truncado (máx. 10 000 caracteres). Pasa query para una búsqueda de texto completo sin distinción de mayúsculas y minúsculas en los textos de las respuestas: total pasa a ser el recuento exacto de respuestas coincidentes y cada elemento devuelve snippet y match_count en lugar de la response completa.

GET/answers/:id

Obtén una única respuesta de IA con todos los detalles, incluidas menciones, citaciones, sentimientos y fuentes.

Menciones y citaciones

Los registros brutos que hay detrás de las métricas de visibilidad: una fila por mención de marca o por URL citada. Consúltalos para tu propia marca, para competidores o para ambos en un único flujo.

GET/dimensions/mentions

Lista las menciones creadas por tu proyecto.

GET/dimensions/citations

Lista las citaciones creadas por tu proyecto.

GET/dimensions/competitor_mentions

Lista las menciones de competidores detectadas en tus ejecuciones.

GET/dimensions/competitor_citations

Lista las citaciones de competidores detectadas en tus ejecuciones.

GET/dimensions/all_mentions

Endpoint unificado que combina las menciones de la marca y de los competidores. Cada registro incluye un campo actor_type (project o competitor).

GET/dimensions/all_citations

Endpoint unificado que combina las citaciones de la marca y de los competidores. Cada registro incluye un campo actor_type (project o competitor).

Sentimientos

Registros de sentimiento con sus comentarios, temas y puntuaciones, además del catálogo de categorías utilizado para etiquetarlos.

GET/sentiments

Lista los registros de sentimiento detallado con todo el contexto del análisis.

GET/dimensions/sentiments

(Opcional) Enumera los grupos de sentimiento disponibles y sus nombres de métrica.

Fuentes e inteligencia de citaciones

Todas las URL que citaron los modelos, además de vistas agrupadas por URL, dominio y host, metadatos de caché de página, evidencia de menciones dentro de las páginas citadas, listas de apariciones y contenido en caché saneado.

GET/dimensions/sources

Enumera las fuentes no rechazadas generadas por las ejecuciones de prompt.

GET/citation_intelligence/groups

Inteligencia de citaciones agrupada por url, domain o host con desglose por modelo, tasa de citaciones y posición media de la citación (ignora las filas con position = 0).

GET/citation_intelligence/mentions_by_domain

Para las respuestas en las que se cita cada dominio de origen indicado, la cuota de esas respuestas que mencionan tu marca frente a cada competidor. La marca y los competidores se normalizan para que sumen 100 % por dominio, siguiendo la definición de mención del Share of Voice. Pasa varios dominios para analizar la matriz completa en una sola llamada.

GET/citation_intelligence/urls/:url_sha256

Detalle a nivel de URL de una página citada: totales, tasa de citaciones, posición media de la citación, recuentos por tipo de fuente, recuentos por modelo, variantes de URL distintas, metadatos de la caché de página y evidencia de menciones en la página con fragmentos y etiquetas de actor.

• Parámetros: project_id (obligatorio), :url_sha256 (64 caracteres hexadecimales en la URL), los mismos filtros opcionales que /citation_intelligence/groups. ERR_NOT_FOUND solo cuando el proyecto nunca ha citado la URL; los filtros que vacían el resultado siguen devolviendo 200 con estadísticas a cero.

GET/citation_intelligence/urls/:url_sha256/occurrences

Ocurrencias paginadas de una URL citada en las ejecuciones de prompt, con extracto de la respuesta, texto del prompt, modelo, executed_at, citation_position y source_type por fila.

• Parámetros: project_id (obligatorio), :url_sha256 (64 caracteres hexadecimales), page, per_page y los mismos filtros opcionales que /citation_intelligence/groups.

GET/citation_intelligence/urls/:url_sha256/content

Contenido saneado de la página en caché para una URL citada: metadatos de la caché de página, evidencia de menciones y fragmentos, texto plano completo y HTML renderizado (se eliminan los scripts y el marcado no seguro).

AI Model Insights

Partes agregadas del informe AI Model Insights de la aplicación. Los tres endpoints filtran por executed_at (no por created_at) y comparten una estructura de actor estándar: { type, id, competitor_id, name, domain }, con dominios simples (sin esquema).

GET/reports/ai_model_insights/summary

Recuentos y cuotas de menciones por modelo, recuentos y cuotas de citaciones, sentimiento neto de la marca con recuentos brutos de positivos y negativos, totales y cuotas de visibilidad ponderada, además de las matrices de actores para cada modelo.

GET/reports/ai_model_insights/position_distribution

Comparativa de distribución de posiciones utilizada en el informe AI Model Insights: una o dos series de marcas con totales por intervalos (Posición 1, Posición 2-3, Posición 4-7, Posición 8+) y series temporales listas para gráficos por intervalo.

GET/reports/ai_model_insights/ai_overview_results

Datos agregados de disponibilidad de resultados de Google AI Overview: total de respuestas de AI Overview, respuestas con resultados (no_result = false), tasa de resultados, datos de tendencia listos para gráficos y una tabla paginada de tasa de resultados por prompt.

Tráfico de IA y de agentes

Lo que la IA envía realmente a tu sitio: el tráfico de referencia cubre a las personas que llegan desde asistentes de IA y el tráfico de agentes cubre los rastreadores de IA que acceden a tu servidor de origen.

GET/metrics/ai_traffic

Devuelve el tráfico referido por IA medido a partir del proveedor de analítica web conectado del proyecto (Google Analytics 4, Adobe Analytics, PostHog, Plausible o Piano): usuarios, sesiones y conversiones diarios agrupados por fuente de IA (ChatGPT, Perplexity, Gemini, Claude y otras), con totales y una tasa de conversión. Requiere el plan Scale o superior y un proveedor conectado; los proyectos sin proveedor devuelven ERR_AI_TRAFFIC_NOT_CONNECTED (404).

GET/metrics/agent_traffic

Tráfico de bots de IA agregado para un proyecto, agrupado por bot o por empresa, con granularidad diaria, semanal o mensual.

GET/dimensions/agent_bots

Catálogo estático de los bots de IA que Agent Analytics puede identificar. Úsalo para mostrar las interfaces de filtrado que reflejan nuestra clasificación interna (slug, nombre para mostrar, empresa, categoría, asignación de bots verificados de Cloudflare). Requiere el plan Scale o superior; la herramienta MCP list_agent_bots está disponible en todos los planes.

Compras y anuncios

Espacios comerciales dentro de las respuestas de IA: las tarjetas de producto que devuelven los modelos y los emplazamientos de pago que aparecen junto a ellas, con los comercios y anunciantes que hay detrás de cada una. Requisito: plan Scale o superior. Ambos endpoints reciben el nombre de lo que miden y no del asistente que lo devolvió por primera vez, así que filtra con model en lugar de deducir el proveedor de la ruta.

GET/dimensions/shopping

Tarjetas de producto devueltas dentro de las respuestas de IA. view=products (por defecto) devuelve una fila por producto distinto, combinado entre ejecuciones, con su número de apariciones, rango de precios, valoración y si es tuyo. view=merchants devuelve una fila por comercio vendedor. Un producto se identifica por su id de producto externo y recurre a su título cuando el proveedor no envía uno utilizable, por lo que el mismo producto se combina entre ejecuciones en lugar de dividirse en una fila por respuesta.

GET/dimensions/ads

Emplazamientos de pago devueltos dentro de las respuestas de IA. view=advertisers (por defecto) devuelve una fila por dominio anunciante con su número de emplazamientos, alcance de prompts, posición media y mejor posición. view=ads devuelve los emplazamientos individuales con título, snippet, posición y el prompt que los generó. La posición 1 es la mejor, por lo que una posición media más baja es mejor.

Medios propios y comunidades

Qué canales propios y qué conversaciones de comunidad citan las respuestas de IA. Se devuelven todas las filas de la plataforma, no solo las tuyas, y cada una incluye un indicador yours para que puedas comparar tu presencia con la de los demás citados allí. Requisito: plan Growth o superior.

GET/dimensions/owned_media

Citaciones de medios propios de una plataforma. provider es obligatorio y no tiene valor por defecto: omitirlo devuelve ERR_INVALID_PARAM. Las vistas dependen del proveedor: youtube admite videos (por defecto), channels, own_citations; las plataformas sociales admiten posts (por defecto), profiles, own_citations; mobile_apps admite apps. own_citations devuelve solo las citaciones del perfil conectado y permanece vacío hasta que se conecta un perfil. Reddit tiene su propio endpoint más abajo. Por defecto, los últimos 30 días.

GET/dimensions/reddit

Contenido de Reddit citado por las respuestas de IA. view=subreddits (por defecto) devuelve una fila por subreddit con su recuento de citaciones, autores únicos y el desglose de sentimiento positivo/negativo. view=authors devuelve una fila por autor. view=threads devuelve cada hilo citado con sus votos a favor, comentarios, posición media y sentimiento dominante. El filtro brand lee las marcas mencionadas en el contenido de Reddit rastreado, no en la respuesta de IA. Por defecto, los últimos 30 días.

Reputación y estudios

Informes analíticos multimodelo: la puntuación mensual de reputación de tu marca frente a sus competidores y los estudios de IA personalizados que defines sobre cualquier tema y dimensión. Las puntuaciones proceden de varios modelos analistas de forma independiente, así que compara modelos en lugar de promediarlos a ciegas. Requiere monitorización de reputación en la cuenta.

GET/reputation/reports

Los informes mensuales de reputación de un proyecto, del más reciente al más antiguo. Los informes pendientes y fallidos se incluyen a propósito, porque a menudo la pregunta es si este mes llegó a ejecutarse. Cada fila incluye el id del informe, su estado y qué modelos analistas generaron datos.

GET/reputation/reports/:id

Un informe devuelve puntuaciones como filas planas: una fila por modelo analista, marca, dimensión y atributo, con su puntuación de 0-100 y el razonamiento que dio el modelo. Un model desconocido devuelve ERR_INVALID_PARAM en lugar de una lista vacía, y brand se compara de forma exacta en lugar de por subcadena.

GET/studies

Los estudios de IA personalizados definidos en la cuenta. Los estudios pertenecen a la cuenta y no a un proyecto, así que project_id es un filtro opcional aquí y se devuelven los estudios de la cuenta independientemente del proyecto por el que filtres.

GET/studies/:id

Un estudio con su contexto, los sujetos que compara, las dimensiones con las que los puntúa y su historial de informes. Usa los id de reports con el endpoint que aparece a continuación.

GET/studies/:id/reports/:report_id

Un informe de estudio personalizado devuelve puntuaciones como filas planas, con la misma estructura que las puntuaciones del informe de reputación: una fila por modelo analista, sujeto, dimensión y atributo.

Search Console

Datos de rendimiento de Google Search Console (impresiones, clics, CTR, posición media) para proyectos con una propiedad de GSC conectada. Requisito: plan Growth o superior. ctr es una fracción entre 0 y 1 y position es la media ponderada por impresiones, igual que en la API de Search Console.

GET/search_console/summary

Totales principales de toda la propiedad para el período, con un desglose opcional por país o dispositivo agregado en el mismo período.

GET/search_console/timeseries

Series de toda la propiedad agrupadas por día, semana o mes.

GET/search_console/queries

Las principales consultas de búsqueda del período, ordenadas y paginadas. Cuenta deliberadamente de menos las consultas anonimizadas, por lo que no suman exactamente los totales del resumen (igual que en la interfaz de GSC).

GET/search_console/pages

Las principales páginas de destino del período, ordenadas y paginadas. Misma estructura que el endpoint de consultas, donde la clave de cada fila es la URL de una página.

Recomendaciones

Las mismas ejecuciones de recomendación que alimentan la página Recomendaciones de la aplicación, más el endpoint que lanza una nueva.

GET/recommendations

Lista las ejecuciones de recomendaciones de un proyecto con filtros por tipo y estado.

GET/recommendations/:id

Una ejecución de recomendación con sus elementos y los datos del informe: array de elementos con título, prioridad, pasos de acción, metadatos y referencias de fuentes, además del recuento de elementos agrupado por active, completed, archived.

POST/recommendations

Lanza una nueva generación (el mismo motor que la página de Recomendaciones de la app). Se ejecuta de forma asíncrona (1-3 minutos); sondea GET /recommendations/:id hasta que el estado sea completed. Consume el presupuesto semanal de elementos de recomendación del proyecto (ERR_LIMIT_REACHED cuando se agota, o cuando ya hay una ejecución del mismo tipo pendiente). sentiment_reputation requiere Scale o superior. Requiere una clave de API con permisos de escritura.

GEO Writer

Crea y gestiona tareas de GEO Writer con IA. Las tareas se procesan de forma asíncrona, así que crea una y haz polling hasta que se complete.

POST/intelligence_tasks

Crea una tarea de GEO Writer. Dos modos: basado en prompt (proporciona prompt_id) o generación con IA (proporciona custom_topic y/o user_instructions).

GET/intelligence_tasks

Lista las tareas de GEO Writer de un proyecto con filtrado opcional.

GET/intelligence_tasks/:id

Obtén todos los detalles de la tarea, incluidos los datos del resultado una vez completada. Acepta el ID numérico o el public_id.

Informes técnicos de GEO

Ejecuta el paquete de análisis técnico de GEO (rastreabilidad, schema, preparación del contenido, descubribilidad, estructura del sitio, robots.txt, preparación para agentes, llms.txt, visibilidad en IA) para una URL.

POST/technical_geo_reports

Lanza el paquete completo de análisis técnico GEO (rastreabilidad, schema, preparación de contenido, descubribilidad, estructura del sitio, robots.txt, preparación para agentes, llms.txt, visibilidad en IA) para una URL y un país. Cada informe se ejecuta como un trabajo en segundo plano.

Anotaciones

Marca una fecha en la cronología del proyecto (el lanzamiento de una campaña, una migración del sitio, un rediseño) para que un gráfico muestre qué ocurrió y cuándo. Disponible en todos los planes.

POST/annotations

Marca una fecha en la serie temporal del proyecto con un título y una descripción. Disponible en todos los planes.

GET /annotations + PATCH/DELETE /annotations/:id

Lista, actualiza y elimina anotaciones en todos los planes. GET devuelve las anotaciones manuales, automáticas, de Test GEO y de plataforma, primero las más recientes. El campo origin las distingue y editable indica si el usuario que realiza la solicitud puede modificar la fila. PATCH y DELETE solo funcionan sobre anotaciones manuales que pertenezcan a tu propio usuario (403 en caso contrario).

• Parámetros de GET: project_id (obligatorio), from/to (YYYY-MM-DD), annotation_category_id, page, per_page. Cuerpo de PATCH: cualquiera de title, description, annotation_date, color, annotation_category_id. DELETE: project_id + :id en la URL.

Webhooks

Recibe un HTTP POST firmado cada vez que ocurre algo en un proyecto, sin necesidad de polling. Los webhooks alimentan los conectores de LLM Pulse para Zapier, Make y n8n y funcionan con cualquier backend personalizado. Disponible en el plan Scale o superior.

• Tipos de evento: mention.created, competitor_mention.created, citation.created, prompt_execution.completed, sentiment.negative_detected (sentimiento de marca negativo o muy negativo), recommendation.completed, intelligence_task.completed.
• Seguridad: cada entrega incluye X-LLMPulse-Event, X-LLMPulse-Delivery (id único) y X-LLMPulse-Signature (sha256=<hex>, HMAC-SHA256 del cuerpo en bruto calculado con el secreto de la suscripción). Verifica la firma para autenticar las entregas.
• Entrega: una respuesta 2xx confirma el evento; cualquier otra se reintenta 5 veces con retroceso exponencial. Las suscripciones se desactivan automáticamente tras 20 entregas fallidas consecutivas.

POST/webhooks

Crea una suscripción. Idempotente: volver a enviar el mismo proyecto + evento + URL devuelve la suscripción existente. El secreto de firma (whsec_...) solo lo devuelve este endpoint; guárdalo para verificar las firmas de las entregas. Requiere una clave con ámbito read_write.

GET/webhooks

Lista las suscripciones activas de la cuenta. Los elementos coinciden con la respuesta de creación, sin el secreto.

DELETE/webhooks/:id

Elimina una suscripción. La URL de destino deja de recibir eventos de inmediato. Requiere una clave con ámbito read_write.

GET/webhooks/sample/:event_type

Hasta 3 payloads de ejemplo por tipo de evento, generados a partir de los datos reales más recientes del proyecto (o una muestra estática si el proyecto aún no tiene datos). Lo usan editores de integraciones como el cargador de ejemplos de Zapier. También disponible como herramienta MCP get_webhook_sample.

Ejemplos de código de cliente

Examples in multiple languages are shown in the code panel on the right.

Postman: descarga y entorno

Usa esta colección de Postman seleccionada para explorar la API con rapidez y seguridad. Refleja los ejemplos y la semántica de métricas descritos arriba (totales del período con arrastre persistente, proporción de sumas del período para la visibilidad y propagación para avg_position), para que puedas validar las respuestas y crear prototipos de integraciones en minutos.

Descargar la colección

Descarga la colección de Postman de LLMPulse API v1

Importa el archivo en Postman (Archivo → Importar) y, a continuación, selecciona o crea el entorno que se muestra abajo. La colección usa variables, así que no tendrás que editar cada solicitud manualmente.

Entorno (marcadores de posición, mantén tus ID privados)

Crea un entorno nuevo en Postman con las siguientes variables. Usa marcadores de posición en lugar de ID o claves reales en cualquier contexto público (documentación, capturas de pantalla, etc.):

Cómo se usa:

• La colección lee {{base_url}} e inyecta Authorization: Bearer {{api_key}} automáticamente.
• Configura {{project_id}} con un proyecto que poseas; {{competitors}} es un CSV (p. ej., 1,2,3).
• Puedes sobrescribir estos valores por solicitud (p. ej., enviar from/to en lugar de range) y añadir filtros como model, collection_id, country_code, language_code.
• Mantén tu clave de API solo en tu entorno privado; no la pegues en documentos compartidos.

MCP (integración con IA)

MCP (Model Context Protocol) permite a los asistentes de IA como ChatGPT, Claude y Gemini acceder directamente a tus datos de LLM Pulse. Disponible en todos los planes mediante OAuth, sin necesidad de clave de API. Haz preguntas en lenguaje natural y deja que la IA recupere y analice tus datos de visibilidad.

¿Qué es MCP?

MCP es un protocolo abierto que permite a los asistentes de IA conectarse a fuentes de datos externas. En lugar de copiar datos o hacer llamadas a la API manualmente, puedes simplemente hacerle preguntas a tu asistente de IA como «¿Cuál es mi tendencia de visibilidad este mes?» y obtendrá los datos automáticamente.

Endpoint

Tarjeta de servidor

Una tarjeta de servidor pública describe este servidor MCP a los clientes antes de que dispongan de ninguna credencial: el endpoint, su transporte Streamable HTTP, las versiones de protocolo que acepta y la cabecera Authorization que deben enviar. Puedes obtenerla con GET /api/v1/mcp/server-card (no requiere autenticación y no contiene ninguna credencial). También se anuncia en el catálogo de descubrimiento en /.well-known/ai-catalog.json.

Configuración

Recomendado para todos los planes: pega la URL de MCP en tu cliente de IA. El cliente gestiona OAuth automáticamente, sin necesidad de copiar ningún token. La autenticación con clave de API (cabecera Bearer) está disponible a partir del plan Scale para integraciones headless.

¿Tienes problemas para conectarte?

El soporte de MCP y OAuth todavía es desigual entre los clientes de IA, por lo que a veces no se consigue establecer la conexión. A partir del plan Scale, la alternativa más sencilla es dar a tu asistente de IA una clave de API Bearer junto con un enlace a esta documentación de la API. Así podrá consultar todos los endpoints directamente mediante HTTP simple, sin necesidad de configurar ningún cliente MCP.

Herramientas disponibles

Estas herramientas están disponibles para tu asistente de IA.

Live list rendered from Mcp::LlmPulseServer::TOOLS (86 tools registered). The MCP server filters tools/list per user plan.

Protocolo

MCP usa JSON-RPC 2.0 sobre Streamable HTTP. Las solicitudes devuelven una respuesta JSON-RPC. Las notificaciones aceptadas devuelven HTTP 202 con el cuerpo vacío.

Para una guía más sencilla, consulta la página de configuración de MCP.

OAuth 2.1 (ChatGPT Apps SDK, clientes MCP)

Servidor de autorización OAuth 2.1 con PKCE-S256, registro dinámico de clientes (RFC 7591) y metadatos de descubrimiento (RFC 8414 + RFC 9728). Lo usan el SDK de ChatGPT Apps y cualquier otro cliente MCP compatible con OAuth. Disponible en todos los planes para el recurso MCP en /api/v1/mcp. Los tokens de acceso JWT firmados con RS256 y el refresh token reutilizable comparten una fecha límite de autorización fija de un año.

Resumen de OAuth 2.1

Usa OAuth 2.1 cuando tu cliente necesite acceso delegado por usuario al endpoint MCP y no puedas distribuir una API key (por ejemplo, un asistente de IA multiinquilino). Usa API keys cuando controles ambos extremos y quieras una integración más simple (plan Scale o superior). El MCP vía OAuth está disponible en todos los planes, incluida la prueba gratuita.

Endpoints: /oauth/authorize, /oauth/token, /oauth/register, /oauth/jwks.json, /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource.

GET/.well-known/oauth-authorization-server

Metadatos del servidor de autorización en /.well-known/oauth-authorization-server (RFC 8414) y metadatos del recurso protegido en /.well-known/oauth-protected-resource (RFC 9728). Las JWKS que se usan para verificar las firmas de los tokens de acceso se encuentran en /oauth/jwks.json. Los clientes deben consultarlos para descubrir los endpoints authorize, token y registration, y nunca fijarlos en el código.

Sin parámetros. Devuelve JSON con issuer, authorization_endpoint, token_endpoint, registration_endpoint, jwks_uri, scopes_supported, code_challenge_methods_supported y metadatos relacionados.

POST/oauth/register

Registro dinámico de clientes según RFC 7591. Sin autenticación y con un límite de 5 solicitudes por hora por IP. Solo se persisten los campos RFC 7591 (los campos adicionales se descartan). Las redirect URIs deben ser HTTPS (cualquier host) o loopback HTTP (localhost / 127.0.0.1); los esquemas personalizados como javascript:, data:, file: se rechazan. Máximo 10 redirect URIs por cliente; client_name limitado a 200 caracteres; URIs limitadas a 2048 caracteres.

Cuerpo JSON: redirect_uris (array obligatorio), client_name, grant_types (por defecto, authorization_code refresh_token), token_endpoint_auth_method (none para clientes PKCE públicos, client_secret_post para confidenciales), scope.

GET/oauth/authorize

Muestra una pantalla de consentimiento integrada en la app. Tras la aprobación, redirige al usuario de vuelta a redirect_uri con un code de un solo uso (TTL de 10 minutos) y el state original. PKCE-S256 es obligatorio; los desafíos plain se rechazan.

Parámetros: response_type=code (obligatorio), client_id (obligatorio), redirect_uri (obligatorio, debe coincidir exactamente con una URI registrada), code_challenge (obligatorio), code_challenge_method=S256 (obligatorio), scope (separado por espacios: mcp:read mcp:write), state, resource (indicador de recurso RFC 8707).

POST/oauth/token

Intercambia un código de autorización por un access token + refresh token, o renueva un access token. Usa application/x-www-form-urlencoded. Límite de 60 solicitudes por minuto por IP. Las respuestas de renovación devuelven el mismo refresh token reutilizable, y todas las credenciales caducan en la fecha límite de autorización fija de un año.

Cuerpo: grant_type (authorization_code o refresh_token), client_id (obligatorio), client_secret (obligatorio para clientes confidenciales) y o bien {code, code_verifier, redirect_uri} o bien {refresh_token, scope opcional para reducir el alcance}.

Scopes y verificación de la audiencia

Se definen dos scopes. mcp:read concede acceso a todas las herramientas de lectura (list_*, get_*). mcp:write concede además las herramientas de escritura (create_prompts, create_competitor, create_collection, assign_prompt_tags, create_annotation, create_intelligence_task, launch_recommendations, create_technical_geo_report). Un token emitido solo con mcp:read no puede invocar herramientas de escritura: tanto tools/list las oculta como una llamada directa a tools/call devuelve un error. La claim aud del JWT debe coincidir con la URL del servidor de recursos; los tokens con una audiencia distinta se rechazan en /api/v1/mcp.

Al renovar un token, puedes pasar un scope más restringido; cualquier alcance más amplio que la concesión original devuelve invalid_grant.

Registro de cambios

Los tres cambios más recientes de la API. El historial completo está en su propia página.

• 2026-08 (mediados): Actualización del perfil de proyecto y Brand Book al crear (v1.31.0). El nuevo endpoint PATCH /api/v1/projects/:id actualiza el perfil de un proyecto después de su creación, con los mismos campos que en Configuración del proyecto: brand_name, description, industry, business_model, target_audience, brand_voice, goals, primary_products y matching_names. Los campos del Brand Book (description, industry, brand_voice, target_audience) alimentan a GEO Writer, las sugerencias de prompts y las Recomendaciones, de modo que los sistemas externos puedan mantener el contexto de marca sincronizado mediante programación. Envía solo los campos que quieras cambiar; los campos desconocidos devuelven ERR_INVALID_PARAM. Cambiar matching_names (una lista de sustitución completa) vuelve a ejecutar el emparejamiento de menciones/citaciones sobre el historial del proyecto en segundo plano (rematching: true; se rechazan más ediciones mientras se ejecuta), y un cambio de brand_name solo se aplica a ejecuciones futuras. POST /api/v1/projects (y la herramienta MCP create_project) ahora acepta business_model, target_audience, brand_voice, goals y primary_products en el momento de la creación. La herramienta MCP existente update_project y el nuevo endpoint REST comparten exactamente el mismo servicio. Requiere una clave read_write; los miembros del equipo necesitan el permiso de actualización de Proyectos.
• 2026-08 (mediados): Correcciones de filtros en los nuevos listados (v1.30.0). Los filtros que estaban documentados pero se ignoraban silenciosamente ahora funcionan. store (medios propios) y status (hilos de Reddit) llegan a la consulta en lugar de descartarse, así que store=app_store y status=archived dejan de devolver filas sin filtrar. owned=true se aplica a GET /dimensions/shopping?view=merchants, que antes devolvía todos los comercios incluidos los competidores, y a GET /dimensions/owned_media?provider=mobile_apps, cuyas filas ahora incluyen el indicador yours que ya devolvía el resto de proveedores. En ese mismo proveedor, total es ahora el recuento completo del ranking (con un tope de 500) en lugar del tamaño de la página, que hacía creer a los clientes que paginan que no había nada después de la página 1. direction=desc ahora se aplica a las ordenaciones de texto de GET /dimensions/query_fan_outs (order=query_text, order=prompt_text), que siempre respondían en orden ascendente; ambos ahora se ordenan por defecto en orden descendente, como el resto de ordenaciones. El parámetro view de un endpoint por fin puede combinarse con output=flat o output=csv (por ejemplo ?view=merchants&output=csv), algo que antes devolvía ERR_INVALID_PARAM, y las respuestas planas devuelven view, provider y store. GET /account ahora informa del límite de solicitudes de la clave con la que se ha llamado en lugar del predeterminado, y su bloque subscription se limita a quienes pueden acceder a Planes y facturación. Los estudios se limitan a los proyectos a los que puede acceder quien llama.
• 2026-08 (mediados): Seis nuevas superficies de producto (v1.29.0). Compras y emplazamientos de pago dentro de las respuestas de IA: GET /api/v1/dimensions/shopping y GET /api/v1/dimensions/ads (Scale+). Medios propios y comunidades: GET /api/v1/dimensions/owned_media (YouTube, Instagram, Facebook, TikTok, LinkedIn, tiendas de aplicaciones) y GET /api/v1/dimensions/reddit (Growth+). Informes analíticos multimodelo: GET /api/v1/reputation/reports, GET /api/v1/reputation/reports/:id, GET /api/v1/studies, GET /api/v1/studies/:id y GET /api/v1/studies/:id/reports/:report_id (requiere monitorización de reputación). Las rutas de shopping y ads son deliberadamente independientes del modelo en lugar de llevar el nombre de un asistente concreto, ya que los datos subyacentes siempre han llevado la enumeración estándar de modelos. Nueve herramientas MCP equivalentes: list_shopping_products, list_ads, list_reddit_citations, list_owned_media, list_reputation_reports, get_reputation_report, list_studies, get_study, get_study_report. Los nueve endpoints admiten output=flat y output=csv.