Monitores de marca y de categoría
Un monitor tiene unmode, 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.
positiones el offset de carácter de la primera coincidencia, onullcuando la marca no aparece. - Citada: la respuesta cita una página de uno de tus
domainso de un subdominio suyo. - Coincidencias de competidores: qué competidores del monitor aparecen en la misma respuesta.
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
quality y después stats, brands y opportunities. Cada campo se explica en
Informes y métricas.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ú llevansource: "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.
competitorsReadAtindica cuándo fue la última lectura. - Al actualizar,
competitorssustituye tu propia lista y conserva las encontradas. Las entradas consource: "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 delintervalHoursdel monitor, hasta 168. El motor participa cada k ejecuciones, contando desde la primera, en la que participan todos los motores.
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:locationpregunta cada prompt desde un punto, en grados decimales.gridpregunta cada prompt desde cada punto de una cuadrícula cuadrada alrededor decenter.sizees 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.
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 endisplay.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á enanswer.analysisdeGET /v1/monitors/{id}/answers/{taskId}.
location o grid suma 1 crédito a cada tarea.
Leer informes, fuentes, respuestas y resultados no cuesta nada.
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_ERRORindicando 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.
nextRunAtes cuándo vence la siguiente ejecución. Reanudar un monitor pausado, o cambiarintervalHours, 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.
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.
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 conpromptTopics:
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: falsepausa el monitor;enabled: truelo reanuda con la siguiente ejecución dentro de un intervalo. Las pausas aparecen en los informes comopauses.- Cambiar
alertBelowPctvuelve 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 enhttps://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:
GET /v1/monitors/capabilities: motores, precios y límites antes de gastar nada.GET /v1/monitors: reutiliza un monitor del tema y mercado, o crea uno, opcionalmente a partir dePOST /v1/monitors/suggest.POST /v1/monitors/{id}/runsolo si necesitas respuestas antes de la siguiente ejecución programada.GET /v1/monitors/{id}/analytics?days=30: leequalityantes que las cifras y espera a quehealth.pendingllegue a0.GET /v1/monitors/{id}/sources?days=30&groupBy=page: siguenextCursorhasta el final.GET /v1/monitors/{id}/answers/{taskId}: abre la respuesta que hay detrás de la primera entrada deopportunitiesantes de actuar.GET /v1/monitors/{id}/results?since=...&until=...&format=csv: exporta la misma ventana siguiendox-next-cursorhasta 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.