> ## Documentation Index > Fetch the complete documentation index at: https://docs.querying.ai/llms.txt > Use this file to discover all available pages before exploring further. # Prompt Research > Las preguntas que la gente hace a los asistentes de IA sobre un tema, ordenadas por la demanda de búsqueda mensual detrás de cada una Envía un tema y recibe las preguntas que la gente le haría a un asistente de IA sobre él, ordenadas según cuántas personas buscan esa necesidad cada mes, y el conjunto de ellas que un [monitor GEO](/es/monitors) debería seguir, en el orden en que conviene añadirlas. Úsalo para elegir los prompts de un monitor y para ver qué marcas competidoras atraen demanda en el mismo espacio. ```bash theme={null} curl -X POST https://api.querying.ai/v1/prompt-research \ -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \ -d '{ "seed": "선크림", "country": "KR", "limit": 20, "brand": "MyBrand" }' ``` La solicitud devuelve una tarea en cola. Sondea `GET /v1/async/task/:id` o indica `webhook.url` al enviarla; la tarea aparece con `taskType: "PROMPT_RESEARCH"` y suele completarse en 30–60 segundos. No la envíes con `POST /v1/async/task`; usa este endpoint. ## Payload | Campo | Obligatorio | Notas | | - | - | - | | `seed` | sí | El tema: de 1 a 30 caracteres entre letras, dígitos y espacios simples, como `선크림` o `무선청소기`. Funciona mejor un término corto de producto o categoría; una frase no encuentra nada. | | `country` | sí | `KR` (Corea del Sur) o `US` (Estados Unidos). Cualquier otro valor se rechaza con `422 REGION_UNSUPPORTED`. Los prompts salen en el idioma del mercado: coreano para `KR`, inglés para `US`. | | `limit` | no | Prompts que se devuelven, de 1 a 50. Por defecto, 20. | | `exclude[]` | no | Hasta 20 términos de 1 a 30 caracteres. Un prompt que contenga alguno se deja fuera. Úsalo para un subtema que no te interese; tu propia marca va en `brand`. | | `monitorSize` | no | Prompts en `monitorSet`, de 1 a 50. Por defecto, 20. | | `monitorEngines[]` | no | Los motores que ejecutará tu monitor, hasta 12, con los nombres de los [monitores](/es/monitors): `CHATGPT`, `GEMINI`, `PERPLEXITY`, `GOOGLE`, `AIMODE`, `NAVER_AI_BRIEF`, `NAVER_AI_TAB`. Un monitor ejecuta como máximo 200 tareas de prompt × motor a la vez, así que si `monitorSize` × el número de motores supera 200, la solicitud se rechaza con `422 VALIDATION_ERROR` en `monitorSize`. No cambia el resultado. | | `brand` | no | Tu marca: de 1 a 80 caracteres con al menos dos letras o dígitos; admite signos de puntuación. Los prompts que la contengan se dejan fuera, como con `exclude`. | | `brandAliases[]` | no | Hasta 10 nombres o grafías alternativos de tu marca, que se dejan fuera de la misma forma. Requiere `brand`. | | `brandDescription` | no | Hasta 500 caracteres sobre qué vende tu marca y a quién. Requiere `brand`. Con ella, cada prompt lleva un `fit` y `monitorSet` da prioridad a los prompts que tu marca responde. | | `idempotencyKey`, `webhook` | no | Igual que en [`POST /v1/async/task`](/es/api-reference/create-task). | ## Resultado De una ejecución para 선크림, recortada a unas pocas entradas: ```json theme={null} { "seed": "선크림", "country": "KR", "language": "ko", "demandSource": { "period": "last_30_days", "fetchedAt": "2026-09-29T05:23:52.548Z" }, "seedMonthlySearchVolume": 24470, "promptsFound": 96, "prompts": [ { "prompt": "선스틱은 어떤 제품을 고르면 좋아?", "topic": "선스틱", "persona": null, "intent": "commercial", "funnelStage": "consideration", "brandMentions": "likely", "monthlySearchVolume": 14670, "demandShare": 0.1334 }, { "prompt": "톤업 선크림은 어떤 제품이 좋아?", "topic": "톤업과 메이크업", "persona": null, "intent": "commercial", "funnelStage": "consideration", "brandMentions": "likely", "monthlySearchVolume": 13500, "demandShare": 0.1227 } ], "monitorSet": { "prompts": [ { "rank": 1, "prompt": "선스틱은 어떤 제품을 고르면 좋아?", "topic": "선스틱", "persona": null, "intent": "commercial", "funnelStage": "consideration", "brandMentions": "likely", "monthlySearchVolume": 14670, "demandShare": 0.1334 }, { "rank": 5, "prompt": "블루라이트 차단 선크림은 효과가 있어?", "topic": "성분과 차단 방식", "persona": null, "intent": "informational", "funnelStage": "awareness", "brandMentions": "sometimes", "monthlySearchVolume": 1240, "demandShare": 0.0113 } ], "coverage": { "demandShare": 0.8278, "topics": { "covered": 13, "total": 20 }, "personas": { "covered": 4, "total": 19 } } }, "topics": [ { "topic": "선크림 추천", "monthlySearchVolume": 21930, "promptCount": 12, "demandShare": 0.1994 }, { "topic": "성분과 차단 방식", "monthlySearchVolume": 19880, "promptCount": 15, "demandShare": 0.1807 } ], "personas": [ { "persona": "남성", "monthlySearchVolume": 6420, "promptCount": 2, "demandShare": 0.0584 } ], "brands": [ { "brand": "시세이도", "monthlySearchVolume": 3410 } ] } ``` ### `prompts[]`, de mayor a menor demanda * `prompt` — la pregunta, en el idioma del mercado, tal como una persona se la haría a un asistente de IA. Nunca nombra una marca: un prompt que nombra una encontraría esa marca en todas las respuestas. * `topic` — el subtema más amplio al que pertenece la necesidad. Los prompts de un subtema comparten la etiqueta; `topics[]` los suma. * `persona` — quién pregunta, cuando las búsquedas nombran un público, una condición o una situación (hombres, padres de bebés, piel grasa); `null` en caso contrario. * `intent` — `informational` (cómo, qué, por qué), `commercial` (elegir, comparar, recomendar) o `transactional` (precio, dónde comprar). * `funnelStage` — `awareness` (conocer la necesidad o la categoría), `consideration` (comparar opciones), `purchase` (precio, dónde comprar) o `post_purchase` (usar lo que compró). * `brandMentions` — si una buena respuesta al prompt nombra marcas, productos o proveedores: `likely` (recomienda, clasifica o compara opciones), `sometimes` (explica, normalmente con productos de ejemplo) o `rarely` (explica un concepto, un método o un uso sin productos). * `fit` — solo cuando envías `brandDescription`: `core` (la descripción dice que tu marca ofrece lo que pide el prompt), `related` (lo que la descripción no menciona) o `none` (la descripción lo excluye, por ejemplo otro público u otro producto). * `monthlySearchVolume` — búsquedas mensuales de la necesidad detrás del prompt. * `demandShare` — la parte de este prompt en la demanda de todos los prompts útiles encontrados, de 0 a 1. ### `monitorSet` Los prompts que un monitor debería seguir, en el orden en que añadirlos, elegidos entre todos los prompts utilizables encontrados, incluidos los que quedan fuera de `limit`. El conjunto da prioridad a los prompts que mucha gente hace y cuyas respuestas dan al monitor algo que medir, repartidos entre temas y personas. Cada entrada tiene los campos de una entrada de `prompts[]` más `rank`, empezando en 1. `coverage` indica cuánto de la investigación recoge el conjunto: * `demandShare` — la parte de las búsquedas detrás de todos los prompts utilizables encontrados que corresponde a los prompts elegidos, de 0 a 1. * `topics`, `personas` — cuántos de los temas y personas encontrados cubre el conjunto, como `covered` de `total`. Cómo se comporta el conjunto: * Un prompt con `fit` `none` nunca se elige, así que el conjunto puede tener menos de `monitorSize` prompts. * `monitorSize` solo corta un mismo orden: los 12 primeros prompts de un conjunto de 20 son el conjunto de 12, así que ampliar un monitor conserva los prompts que ya sigue. * Un monitor ejecuta como máximo 200 tareas de prompt × motor a la vez. Envía `monitorEngines` con los motores que ejecutará tu monitor y un `monitorSize` que no quepa se rechazará al enviarlo: con cinco motores, `monitorSize` puede ser como máximo 40. Para dar prioridad a los prompts que responde tu marca, describe tu marca: ```bash theme={null} curl -X POST https://api.querying.ai/v1/prompt-research \ -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \ -d '{ "seed": "선크림", "country": "KR", "monitorSize": 12, "monitorEngines": ["CHATGPT", "PERPLEXITY"], "brand": "MyBrand", "brandDescription": "Gentle mineral sunscreens for sensitive and dry skin" }' ``` La descripción se evalúa tal como está escrita, así que con una sola línea la mayoría de los prompts quedan como `related`. Para dejar un subtema fuera del conjunto, `exclude` es más fiable. ### `topics[]` y `personas[]` La demanda sumada por tema y por persona sobre todos los prompts útiles encontrados, incluidos los que quedan fuera de `limit`, de mayor a menor. Cada entrada tiene `monthlySearchVolume`, `demandShare` y `promptCount`. Los prompts sin persona no aparecen en `personas[]`. ### `brands[]` Marcas, fabricantes y líneas de producto que la gente busca en este ámbito, con sus búsquedas mensuales. Su demanda queda fuera de `prompts` porque los prompts no nombran marcas. ### Otros campos * `seedMonthlySearchVolume` — búsquedas mensuales del propio `seed`; `null` cuando no hay cifra para él. * `promptsFound` — prompts utilizables antes de aplicar `limit`. * `demandSource` — el periodo que cubren las cifras, y `fetchedAt`. `KR`: `last_30_days`. `US`: `monthly_average_last_12_months`, así que un término estacional aparece más bajo en su pico que las búsquedas de ese mes. ## Cómo leer bien el resultado * **La demanda de búsqueda no es volumen de conversaciones con IA.** Las cifras cuentan búsquedas mensuales en el mercado. Muestran cuánta gente busca una necesidad; no existe una cifra pública de cuántas veces se plantea esa misma necesidad a asistentes de IA. Úsalas para ordenar prompts, no como previsión de tráfico de IA. * **La redacción se genera; las cifras no.** Cada prompt se escribe para su necesidad, y el mismo `seed` puede agruparse de otra forma en otra ejecución: la parte alta de la lista suele ser estable y el final varía. * **Las búsquedas poco frecuentes se dejan fuera.** Los términos buscados menos de 10 veces al mes no tienen demanda informada y no suman nada a un prompt. * **Las proporciones comparan necesidades dentro de una semilla.** `demandShare` muestra cómo se reparte la demanda de búsqueda de esta semilla entre necesidades, temas y personas. No es una cuota de conversaciones con IA, y las proporciones de semillas distintas no se suman. ## Errores y facturación * 12 créditos por tarea completada. Una tarea fallida libera su retención de créditos. * `422 VALIDATION_ERROR` — un campo está fuera de rango, se enviaron `brandAliases` o `brandDescription` sin `brand`, o `monitorSize` × el número de `monitorEngines` supera 200. * `422 REGION_UNSUPPORTED` — `country` no es `KR` ni `US`. * El `error` de una tarea fallida empieza por su código. `NO_SEARCH_DEMAND` significa que no se encontró demanda de búsqueda para el `seed` ni para nada relacionado; prueba con un término más amplio o más común. `NO_RELATED_SEARCHES` significa que el propio `seed` se busca, pero nada relacionado con él; prueba con una expresión más específica que la gente busque. El mismo `seed` vuelve a fallar igual. `KEYWORD_DATA_UNAVAILABLE`, `ANALYSIS_FAILED` y `ANALYSIS_TIMEOUT` son temporales; vuelve a intentarlo en breve.