Prompt Research

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" }'

​

Payload

​

Resultado

{
  "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

• 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.

• 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.

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" }'

​

topics[] e personas[]

​

brands[]

​

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.