> ## 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 > As perguntas que as pessoas fazem a assistentes de IA sobre um tema, ordenadas pela demanda de busca mensal por trás de cada uma Envie um tema e receba as perguntas que as pessoas fariam a um assistente de IA sobre ele, ordenadas por quantas pessoas buscam essa necessidade todo mês, e o conjunto delas que um [monitor GEO](/pt/monitors) deveria acompanhar, na ordem em que vale adicioná-las. Use para escolher os prompts de um monitor e para ver quais marcas concorrentes atraem demanda no mesmo segmento. ```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" }' ``` A requisição retorna uma tarefa na fila. Consulte `GET /v1/async/task/:id` ou informe `webhook.url` no envio; a tarefa aparece com `taskType: "PROMPT_RESEARCH"` e costuma terminar em 30–60 segundos. Não a envie por `POST /v1/async/task`; use este endpoint. ## Payload | Campo | Obrigatório | Observações | | - | - | - | | `seed` | sim | O tema: de 1 a 30 caracteres entre letras, dígitos e espaços simples, como `선크림` ou `무선청소기`. Um termo curto de produto ou categoria funciona melhor; uma frase não encontra nada. | | `country` | sim | `KR` (Coreia do Sul) ou `US` (Estados Unidos). Qualquer outro valor é rejeitado com `422 REGION_UNSUPPORTED`. Os prompts saem no idioma do mercado: coreano para `KR`, inglês para `US`. | | `limit` | não | Prompts a retornar, de 1 a 50. Padrão 20. | | `exclude[]` | não | Até 20 termos de 1 a 30 caracteres. Um prompt que contenha algum deles fica de fora. Use para um subtema que você não quer; a sua própria marca vai em `brand`. | | `monitorSize` | não | Prompts em `monitorSet`, de 1 a 50. Padrão 20. | | `monitorEngines[]` | não | Os motores que o seu monitor vai executar, até 12, com os nomes dos [monitores](/pt/monitors): `CHATGPT`, `GEMINI`, `PERPLEXITY`, `GOOGLE`, `AIMODE`, `NAVER_AI_BRIEF`, `NAVER_AI_TAB`. Um monitor executa no máximo 200 tarefas de prompt × motor por vez, então, quando `monitorSize` × o número de motores passa de 200, a solicitação é rejeitada com `422 VALIDATION_ERROR` em `monitorSize`. Não muda o resultado. | | `brand` | não | A sua marca: de 1 a 80 caracteres com pelo menos duas letras ou dígitos; aceita pontuação. Prompts que a contenham ficam de fora, como com `exclude`. | | `brandAliases[]` | não | Até 10 outros nomes ou grafias da sua marca, que ficam de fora da mesma forma. Requer `brand`. | | `brandDescription` | não | Até 500 caracteres sobre o que a sua marca vende e para quem. Requer `brand`. Com ela, cada prompt recebe um `fit`, e `monitorSet` prioriza os prompts que a sua marca responde. | | `idempotencyKey`, `webhook` | não | Igual a [`POST /v1/async/task`](/pt/api-reference/create-task). | ## Resultado De uma execução para 선크림, reduzida a poucas 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[]`, da maior para a menor demanda * `prompt` — a pergunta, no idioma do mercado, do jeito que uma pessoa faria a um assistente de IA. Nunca cita uma marca: um prompt que cita uma marca a encontraria em todas as respostas. * `topic` — o subtema mais amplo ao qual a necessidade pertence. Prompts do mesmo subtema compartilham o rótulo; `topics[]` os soma. * `persona` — quem pergunta, quando as buscas indicam um público, uma condição ou uma situação (homens, pais de bebês, pele oleosa); `null` caso contrário. * `intent` — `informational` (como, o quê, por quê), `commercial` (escolher, comparar, recomendar) ou `transactional` (preço, onde comprar). * `funnelStage` — `awareness` (conhecer a necessidade ou a categoria), `consideration` (comparar opções), `purchase` (preço, onde comprar) ou `post_purchase` (usar o que comprou). * `brandMentions` — se uma boa resposta ao prompt cita marcas, produtos ou fornecedores: `likely` (recomenda, classifica ou compara opções), `sometimes` (explica, geralmente com produtos de exemplo) ou `rarely` (explica um conceito, um método ou um uso sem produtos). * `fit` — só quando você envia `brandDescription`: `core` (a descrição diz que a sua marca oferece o que o prompt pede), `related` (o que a descrição não menciona) ou `none` (a descrição o exclui, como outro público ou outro produto). * `monthlySearchVolume` — buscas mensais pela necessidade por trás do prompt. * `demandShare` — a parcela deste prompt na demanda de todos os prompts úteis encontrados, de 0 a 1. ### `monitorSet` Os prompts que um monitor deve acompanhar, na ordem em que devem ser adicionados, escolhidos entre todos os prompts utilizáveis encontrados, incluindo os que passam de `limit`. O conjunto prioriza prompts que muitas pessoas fazem e cujas respostas dão ao monitor algo para medir, distribuídos entre tópicos e personas. Cada item tem os campos de um item de `prompts[]` mais `rank`, começando em 1. `coverage` mostra quanto da pesquisa o conjunto abrange: * `demandShare` — a fatia das buscas por trás de todos os prompts utilizáveis encontrados que cabe aos prompts escolhidos, de 0 a 1. * `topics`, `personas` — quantos dos temas e personas encontrados o conjunto cobre, como `covered` de `total`. Como o conjunto se comporta: * Um prompt com `fit` `none` nunca é escolhido, então o conjunto pode ter menos de `monitorSize` prompts. * `monitorSize` só corta uma mesma ordem: os 12 primeiros prompts de um conjunto de 20 são o conjunto de 12, então ampliar um monitor mantém os prompts que ele já acompanha. * Um monitor executa no máximo 200 tarefas de prompt × motor por vez. Envie `monitorEngines` com os motores que o seu monitor vai executar, e um `monitorSize` que não caiba é rejeitado no envio: com cinco motores, `monitorSize` pode ser no máximo 40. Para priorizar os prompts que a sua marca responde, descreva a sua 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" }' ``` A descrição é avaliada como está escrita, então com uma única linha a maioria dos prompts fica `related`. Para deixar um subtema fora do conjunto, `exclude` é mais confiável. ### `topics[]` e `personas[]` A demanda somada por tema e por persona em todos os prompts úteis encontrados, incluindo os que ficam além de `limit`, da maior para a menor. Cada item tem `monthlySearchVolume`, `demandShare` e `promptCount`. Prompts sem persona ficam fora de `personas[]`. ### `brands[]` Marcas, fabricantes e linhas de produtos que as pessoas buscam nesse espaço, com as buscas mensais de cada um. Essa demanda fica fora de `prompts` porque os prompts não citam marcas. ### Outros campos * `seedMonthlySearchVolume` — buscas mensais pelo próprio `seed`; `null` quando não há contagem para ele. * `promptsFound` — prompts utilizáveis antes de aplicar `limit`. * `demandSource` — o período que os números cobrem, e `fetchedAt`. `KR`: `last_30_days`. `US`: `monthly_average_last_12_months`, por isso um termo sazonal aparece mais baixo no pico do que as buscas daquele mês. ## Como ler o resultado corretamente * **Demanda de busca não é volume de conversas com IA.** Os números contam buscas mensais no mercado. Mostram quantas pessoas procuram uma necessidade; não existe contagem pública de quantas vezes a mesma necessidade é levada a assistentes de IA. Use-os para ordenar prompts, não como previsão de tráfego de IA. * **O texto é gerado; os números não.** Cada prompt é escrito para a sua necessidade, e o mesmo `seed` pode ser agrupado de outro jeito em outra execução: o topo da lista costuma ser estável e o final varia. * **Buscas raras ficam de fora.** Termos buscados menos de 10 vezes por mês não têm demanda informada e não somam nada a um prompt. * **As proporções comparam necessidades dentro de uma semente.** `demandShare` mostra como a demanda de busca em torno desta semente se divide entre necessidades, temas e personas. Não é uma parcela de conversas com IA, e proporções de sementes diferentes não se somam. ## Erros e cobrança * 12 créditos por tarefa concluída. Uma tarefa que falha libera a reserva de créditos. * `422 VALIDATION_ERROR` — um campo está fora do intervalo, `brandAliases` ou `brandDescription` foi enviado sem `brand`, ou `monitorSize` × o número de `monitorEngines` passa de 200. * `422 REGION_UNSUPPORTED` — `country` não é `KR` nem `US`. * O `error` de uma tarefa com falha começa com o código. `NO_SEARCH_DEMAND` significa que não foi encontrada demanda de busca para o `seed` nem para nada relacionado; tente um termo mais amplo ou mais comum. `NO_RELATED_SEARCHES` significa que o próprio `seed` é buscado, mas nada relacionado a ele; tente uma expressão mais específica que as pessoas buscam. O mesmo `seed` falha do mesmo jeito de novo. `KEYWORD_DATA_UNAVAILABLE`, `ANALYSIS_FAILED` e `ANALYSIS_TIMEOUT` são temporários; tente de novo em instantes.