Saltar al contenido principal
Creas un monitor una vez. Cada ejecución es un conjunto de tareas asíncronas normales, facturadas al precio de cada motor. Esta página cubre cómo crear, ejecutar y gestionar monitores. Cómo leer las cifras está en Informes y métricas, las respuestas que hay detrás en Fuentes y respuestas, y los webhooks y alertas por correo en Eventos y alertas. Para ver los mismos datos en el panel, consulta la página del producto.

Monitores de marca y de categoría

Un monitor tiene un mode, que se fija al crearlo y no cambia durante toda su vida, porque decide qué significa cada respuesta almacenada. Cada respuesta se puntúa una vez, cuando llega:
  • Mencionada: uno de tus alias aparece en el texto de la respuesta. position es el offset de carácter de la primera coincidencia, o null cuando la marca no aparece.
  • Citada: la respuesta cita una página de uno de tus domains o de un subdominio suyo.
  • Coincidencias de competidores: qué competidores del monitor aparecen en la misma respuesta.
Estas puntuaciones no incluyen sentimiento ni una estimación de cuota de mercado. La posición de un monitor de categoría es un lugar entre las marcas que mencionan las respuestas, nada más. Para obtener sentimiento y recomendaciones por respuesta, activa analysis.

Inicio rápido

1

Crea el monitor

La primera ejecución empieza en cuanto se crea el monitor.
La respuesta es 201 con el monitor almacenado. Guarda data.monitor.id.
2

Espera las respuestas

Las tareas se admiten según lo permita la concurrencia de tu plan, así que una ejecución llega en segundos o minutos. El health.pending del informe cuenta las tareas aún en curso. Lee el informe cuando llegue a 0.
3

Lee el informe

Lee primero quality y después stats, brands y opportunities. Cada campo se explica en Informes y métricas.
Para obtener respuestas antes de la siguiente ejecución programada, llama a POST /v1/monitors/{id}/run.

Crea un monitor

POST /v1/monitors (referencia) valida la definición, la compara con los límites de tu cuenta, la guarda e inicia la primera ejecución. La llamada devuelve 201 antes de que termine esa ejecución. Si la primera ejecución no puede empezar (por ejemplo, porque tu saldo es demasiado bajo), el monitor se crea igualmente y el programador reintenta la ejecución cada minuto. Por ejemplo, la petición del inicio rápido devuelve:

Campos de la petición

Todos los campos de lista aceptan un array JSON o una única cadena separada por saltos de línea. Las entradas se recortan, las vacías se descartan y los duplicados se eliminan.

Motores

Un monitor puede programar los motores de respuesta basados en prompts: CHATGPT, GEMINI, PERPLEXITY, GOOGLE (Google AI Overviews), AIMODE (Google AI Mode), NAVER_AI_BRIEF, NAVER_AI_TAB y NAVER, un nombre obsoleto que se mantiene para los monitores existentes. Los alias GOOGLE_AIO, GOOGLE_AIMODE y NAVER_AI_MODE se aceptan y se guardan como GOOGLE, AIMODE y NAVER_AI_TAB. Los nombres de motor distinguen mayúsculas y minúsculas. Los tipos de tarea de búsqueda, datos web y análisis, como GOOGLE_SERP o CITATION_ANALYSIS, no se pueden programar. Los precios y los detalles de cada motor están en el catálogo de motores. Una clave de API restringida a algunos motores solo puede crear, actualizar o ejecutar monitores que usen esos motores; cualquier otra cosa devuelve 403 KEY_SCOPE_DENIED.

Competidores

No hace falta que listes competidores. Tras la primera ejecución, una lectura semanal de las respuestas recientes del monitor añade las marcas que venden lo mismo que tú y aparecen en al menos dos respuestas: hasta 15 en un monitor de marca y 25 en uno de categoría.
  • Los competidores encontrados llevan source: "auto"; los que indicas tú llevan source: "user". La lectura nunca cambia ni quita los tuyos. Una marca encontrada que las dos lecturas siguientes no detectan se elimina.
  • Cuando cambia la lista encontrada, las respuestas guardadas del monitor se vuelven a puntuar con ella, para que todas las marcas de un informe se midan sobre las mismas respuestas. competitorsReadAt indica cuándo fue la última lectura.
  • Al actualizar, competitors sustituye tu propia lista y conserva las encontradas. Las entradas con source: "auto" en la petición se ignoran, así que puedes reenviar lo que devolvió GET.

Cómo se reconocen los nombres

  • La coincidencia ignora mayúsculas y minúsculas y el ancho de los caracteres (NFKC).
  • Los nombres en alfabeto latino coinciden solo como palabras completas: «replicates» no es una mención de una marca llamada Replicate. Una letra coreana, japonesa, china o tailandesa junto al nombre cuenta como límite de palabra, así que «agoda를» y «ahamoが» mencionan agoda y ahamo. Los nombres en coreano, japonés, chino y tailandés coinciden en cualquier parte del texto.
  • Un nombre de un solo carácter nunca coincide. Dale a esa marca un alias más largo.
  • Cuando dos nombres se solapan, cuenta el que empieza antes y, después, el más largo. «Acme» dentro de un competidor llamado «Acme Pro» es el competidor.
  • Los destinos de enlace, las URL sueltas y los chips de cita se eliminan antes de buscar coincidencias; el texto visible de un enlace se conserva. Una cita cuenta para cited, no como mención.

Escribe prompts que midan algo

  • Un monitor por tema y mercado. «mejor CRM» y «cómo poner precio a un CRM» son intenciones distintas; promediarlas oculta las dos.
  • Redacta los prompts como lo haría un comprador y nunca incluyas tu propia marca. Un prompt que nombra la marca siempre es una mención, así que informa 100 % y no mide nada. Los nombres de competidores en los prompts están bien.

Muestras y cadencia por motor

Las respuestas de IA cambian de una sesión a otra, así que la proporción sobre varias respuestas es más estable que una sola. engineSettings define, por motor, cuántas respuestas recoger por prompt y con qué frecuencia se ejecuta el motor:
  • samples: de 1 a 10 respuestas por prompt y punto en cada ejecución (por defecto 1). Cada una es una tarea aparte en su propia sesión, puntuada y facturada como cualquier otra.
  • intervalHours: un múltiplo del intervalHours del monitor, hasta 168. El motor participa cada k ejecuciones, contando desde la primera, en la que participan todos los motores.
Una entrada solo puede nombrar uno de los motores del monitor y solo acepta estas dos claves. Al actualizar, engineSettings sustituye el valor guardado; una actualización que quita un motor quita su entrada, y una que cambia el intervalHours del monitor vuelve a comprobar los intervalos de los motores con el nuevo valor.

Ubicación y cuadrículas

Por defecto, cada tarea pregunta por el país en su conjunto. Para medir respuestas locales:
  • location pregunta cada prompt desde un punto, en grados decimales.
  • grid pregunta cada prompt desde cada punto de una cuadrícula cuadrada alrededor de center. size es el número de puntos por lado: 3, 5, 7 o 9 (de 9 a 81 puntos). radiusMeters, de 100 a 50 000, es la distancia del centro al punto medio de un lado.
Solo CHATGPT, GEMINI, GOOGLE y AIMODE responden para una ubicación. Un monitor con ubicación o cuadrícula y cualquier otro motor se rechaza con 400 VALIDATION_ERROR. Al actualizar, definir location o grid borra el otro, y null lo borra. Lee las respuestas por punto con GET /v1/monitors/{id}/grid.

Páginas de respuesta

Una respuesta cuya tarea guardó una página lleva su dirección en display.html, y el panel la entrega como archivo con las fuentes dentro. La página es la pantalla real del motor, no una nueva representación del markdown. Las ejecuciones de un monitor no piden página, así que sus respuestas no la llevan. La dirección se lee de la tarea siempre que una la guardó, así que una página guardada sigue abierta desde su respuesta.

Coste y calendario

Una ejecución crea, para cada motor que participa en ella, una tarea por prompt, por punto y por muestra:
points es 1 sin cuadrícula. Por ejemplo, 12 prompts en CHATGPT (1 crédito) y GOOGLE (1,25 créditos) son 24 tareas y 27 créditos por ejecución, unos 810 créditos al mes con un intervalo diario. Con "CHATGPT": { "samples": 5 } el mismo monitor son 72 tareas y 75 créditos por ejecución. Lee los precios actuales de GET /v1/monitors/capabilities en lugar de fijarlos en el código; cómo se retienen y cobran los créditos está en Créditos y límites. Hay dos cargos además de las tareas:
  • Lectura de competidores: 80 créditos cada 30 días por monitor, repartidos entre sus ejecuciones según la cadencia (unos 2,67 créditos por ejecución en un monitor diario y 18,67 en uno semanal). Se cobra cuando todas las tareas de una ejecución se han enviado, así que una ejecución que tu saldo detuvo no paga por ella.
  • Análisis de respuesta: con analysis: true, 1 crédito por tarea, cobrado solo por las respuestas que se analizaron. Las puntuaciones (mentioned, cited, position) no cambian; el resultado de cada respuesta está en answer.analysis de GET /v1/monitors/{id}/answers/{taskId}.
Un monitor con location o grid suma 1 crédito a cada tarea. Leer informes, fuentes, respuestas y resultados no cuesta nada.
El calendario se repite hasta que pausas o eliminas el monitor. La cifra mensual de arriba es el compromiso que asumes al crearlo.
Cómo se comporta el calendario:
  • Una ejecución no es una ráfaga. Las tareas se envían según lo permitan la concurrencia de tu plan y las colas de los motores. Cada minuto el programador continúa donde se detuvo, una tarea por motor cada vez, y los monitores de distintas cuentas se turnan. Una cuenta principal y sus subcuentas comparten un mismo turno.
  • Una ejecución debe caber en su intervalo. Si las tareas de un motor no pueden admitirse antes de que ese motor vuelva a ejecutarse, crear y actualizar devuelven 400 VALIDATION_ERROR indicando el intervalo más corto que cabe. Una ejecución que sigue enviando cuando ha pasado un intervalo completo se cierra, y sus tareas restantes no se envían.
  • Las ejecuciones perdidas no se recuperan. nextRunAt es cuándo vence la siguiente ejecución. Reanudar un monitor pausado, o cambiar intervalHours, programa la siguiente ejecución un intervalo después de ese momento.

Capacidades

GET /v1/monitors/capabilities (referencia) devuelve, para tu cuenta: cada motor programable con creditsPerTask, analysisCreditsPerTask y placeCreditsPerTask, tus limits, los modes, las definiciones de métricas (metrics), las fórmulas del calendario y los tipos de evento de cambio. No tiene efectos secundarios ni coste; llámalo antes de crear monitores de forma programática.

Elige los prompts

Sugiere prompts a partir de datos de la marca

POST /v1/monitors/suggest (referencia) devuelve hasta 12 prompts candidatos redactados como preguntaría un comprador en country. No guarda nada ni gasta créditos.
Por ejemplo:
Las sugerencias que contienen el nombre de la marca o un alias se eliminan. Revisa la lista antes de crear el monitor. Puedes pedir una sugerencia cada 20 segundos y 30 por hora; más devuelve 429 RATE_LIMITED. Cuando el modelo rechaza la marca, la llamada devuelve 400 SUGGEST_FAILED; cuando falla el servicio de sugerencias, 502 SUGGEST_FAILED, y cuando no está configurado, 503 SUGGEST_FAILED.

Investiga prompts a partir de la demanda de búsqueda

POST /v1/monitors/research (referencia) acepta el cuerpo de petición de Prompt Research, cuesta los mismos 14 créditos y devuelve el mismo resultado como una tarea de tu cuenta.
La respuesta lleva la tarea en cola en data.task, con data.credits y data.replayed. Lee el resultado con GET /v1/async/task/{id} usando data.task.id (consulta Tareas asíncronas). Después crea el monitor con prompts[].prompt como prompts, en su orden; en un monitor de categoría, cuando la investigación tiene más de un core, el core de cada prompt como su entrada en promptTopics, y brands[].brand como competitors. No se guarda nada hasta que creas el monitor. Una ejecución puede encolar como máximo el límite tasksPerRun de tu cuenta, contado en cada motor como prompts × puntos de ubicación × samples, así que ajusta limit al monitor que vayas a crear. Consulta De la investigación a un monitor.

Monitores de categoría

Un monitor de categoría ordena las marcas que nombran los motores para un mercado. Agrupa sus prompts por subárea con promptTopics:
Un monitor de categoría no tiene marca propia: aliases, domains y alertBelowPct deben estar vacíos, o la petición devuelve 400 VALIDATION_ERROR, y no tiene alerta. Sus stats.mentioned y stats.cited en GET /v1/monitors siempre son 0; la lista añade leader, la marca más mencionada en los últimos 30 días. Su informe se describe en Informes de categoría. El calendario, el coste, las fuentes, las respuestas, los resultados y los eventos de cambio funcionan igual que en un monitor de marca, salvo que un monitor de categoría solo envía eventos monitor.source.first_cited. Al actualizar, un cambio en prompts quita las entradas de promptTopics de los prompts eliminados. Las respuestas que recogieron esos prompts siguen en el ranking.

Gestiona los monitores

El resumen de periodo antiguo de GET /v1/monitors/{id} se mantiene por compatibilidad. Para las cifras, usa /analytics: el resumen antiguo mezcla una matriz histórica de la última respuesta por prompt y motor con cifras de ventana, corta las fuentes en 12 dominios y 20 páginas, y su shareOfVoice cuenta cada marca frente a todas las respuestas, así que las cuotas pueden sumar más de 100. Un monitor que pertenece a otra cuenta devuelve 404 NOT_FOUND, no 403.

Actualiza un monitor

PATCH acepta cualquier subconjunto de los campos de creación y valida el resultado en su conjunto, con los mismos límites. Los campos que omites conservan sus valores.
  • enabled: false pausa el monitor; enabled: true lo reanuda con la siguiente ejecución dentro de un intervalo. Las pausas aparecen en los informes como pauses.
  • Cambiar alertBelowPct vuelve a armar la alerta.
  • Cambiar alias, dominios o competidores afecta a las respuestas puntuadas a partir de ese momento. Las respuestas guardadas conservan las definiciones con las que se puntuaron, así que los informes ocultan las comparaciones que cruzan el cambio (consulta Informes y métricas).

Ejecuta un monitor ahora

POST /v1/monitors/{id}/run hace que la siguiente ejecución venza de inmediato; el programador la inicia en aproximadamente un minuto y la llamada devuelve data.queued: true. La ejecución se cobra como una programada. Volver a llamarla mientras esa ejecución sigue pendiente no crea una segunda. Antes de ponerla en cola, la llamada comprueba que tu saldo cubre la ejecución, incluidos la lectura de competidores y los créditos de análisis. Si no, devuelve 402 INSUFFICIENT_CREDITS con details.needed y details.available. Una subcuenta por encima de su límite mensual de créditos recibe 429 SUB_ACCOUNT_CREDIT_LIMIT. Un monitor pausado devuelve 404 NOT_FOUND: reanúdalo primero.

Comparte un informe

Puedes publicar el informe de un monitor en https://querying.ai/<slug>. Un informe compartido muestra la analítica, las fuentes, las citas, los resultados y las respuestas; nunca muestra la configuración, las alertas, los controles de ejecución ni la salud de las tareas de tu cuenta. GET /v1/monitors/{id}/share (referencia) devuelve el estado actual, access, slug, locale y url, además de un suggestedSlug cuando no hay ninguno definido. PUT /v1/monitors/{id}/share (referencia) lo cambia:
Poner access en PRIVATE desconecta el informe y conserva el slug, así que al volver a activar la compartición se reutiliza la misma dirección.

Usa monitores desde un agente

El servidor MCP expone los monitores como herramientas: get_monitor_capabilities, list_monitors, get_monitor, create_monitor, update_monitor, delete_monitor, run_monitor, get_monitor_analytics, get_monitor_sources, get_monitor_results, get_monitor_answer, suggest_monitor_prompts, get_monitor_alerts y test_monitor_alert. Cada una hace una llamada a la API con tu clave. Una secuencia práctica para un agente o un script:
  1. GET /v1/monitors/capabilities: motores, precios y límites antes de gastar nada.
  2. GET /v1/monitors: reutiliza un monitor del tema y mercado, o crea uno, opcionalmente a partir de POST /v1/monitors/suggest.
  3. POST /v1/monitors/{id}/run solo si necesitas respuestas antes de la siguiente ejecución programada.
  4. GET /v1/monitors/{id}/analytics?days=30: lee quality antes que las cifras y espera a que health.pending llegue a 0.
  5. GET /v1/monitors/{id}/sources?days=30&groupBy=page: sigue nextCursor hasta el final.
  6. GET /v1/monitors/{id}/answers/{taskId}: abre la respuesta que hay detrás de la primera entrada de opportunities antes de actuar.
  7. GET /v1/monitors/{id}/results?since=...&until=...&format=csv: exporta la misma ventana siguiendo x-next-cursor hasta que esté vacío.

Límites

Una cuenta con contrato es una con un límite de concurrencia negociado. Estos límites se aplican a todas las cuentas: Los límites de informes, tamaño de página y conservación se indican en las páginas que los usan: Informes y métricas, Fuentes y respuestas y Eventos y alertas.

Errores

El formato de error es el mismo que en el resto de la API (consulta Errores). Códigos específicos de los monitores:

Próximos pasos

Informes y métricas

El contrato de /analytics y qué significa cada cifra.

Fuentes y respuestas

Páginas citadas, las respuestas detrás de cada puntuación y exportaciones.

Eventos y alertas

Webhooks cuando cambian las respuestas y alertas por correo sobre tu tasa de mención.

Prompt Research

Encuentra los prompts que vale la pena seguir a partir de la demanda de búsqueda.