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

​

Résultat

{
  "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[], par demande décroissante

• prompt — la question, dans la langue du marché, telle qu’une personne la poserait à un assistant IA. Elle ne nomme jamais de marque : un prompt qui en nomme une trouverait cette marque dans chaque réponse.
• topic — le sous-thème plus large auquel appartient le besoin. Les prompts d’un même sous-thème partagent l’étiquette ; topics[] les additionne.
• persona — qui pose la question, quand les recherches nomment un public, un état ou une situation (hommes, parents de bébés, peau grasse) ; null sinon.
• intent — informational (comment, quoi, pourquoi), commercial (choisir, comparer, recommander) ou transactional (prix, où acheter).
• funnelStage — awareness (découvrir le besoin ou la catégorie), consideration (comparer les options), purchase (prix, où acheter) ou post_purchase (utiliser ce qui a été acheté).
• brandMentions — si une bonne réponse au prompt cite des marques, des produits ou des prestataires : likely (elle recommande, classe ou compare des options), sometimes (elle explique, le plus souvent avec des produits en exemple) ou rarely (elle explique un concept, une méthode ou un usage sans produits).
• fit — uniquement si vous envoyez brandDescription : core (la description indique que votre marque propose ce que demande le prompt), related (ce que la description ne mentionne pas) ou none (la description l’exclut, par exemple un autre public ou un autre produit).
• monthlySearchVolume — les recherches mensuelles pour le besoin derrière le prompt.
• demandShare — la part de ce prompt dans la demande de tous les prompts utilisables trouvés, de 0 à 1.

​

monitorSet

• demandShare — la part des recherches derrière tous les prompts utilisables trouvés que représentent les prompts choisis, de 0 à 1.
• topics, personas — combien des thèmes et personas trouvés l’ensemble couvre, sous la forme covered sur total.

• Un prompt dont le fit est none n’est jamais choisi ; l’ensemble peut donc compter moins de monitorSize prompts.
• monitorSize ne fait que couper un même ordre : les 12 premiers prompts d’un ensemble de 20 forment l’ensemble de 12, donc agrandir un moniteur conserve les prompts qu’il suit déjà.
• Un moniteur exécute au plus 200 tâches prompt × moteur à la fois. Envoyez monitorEngines avec les moteurs de votre moniteur, et un monitorSize qui ne tiendrait pas est rejeté dès la soumission : avec cinq moteurs, monitorSize vaut au plus 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[] et personas[]

​

brands[]

​

Autres champs

• seedMonthlySearchVolume — les recherches mensuelles pour le seed lui-même ; null quand aucun chiffre n’existe.
• promptsFound — prompts utilisables avant l’application de limit.
• demandSource — la période couverte par les chiffres, et fetchedAt. KR : last_30_days. US : monthly_average_last_12_months, si bien qu’un terme saisonnier apparaît plus bas à son pic que les recherches de ce mois-là.

​

Bien lire le résultat

• La demande de recherche n’est pas le volume de conversations IA. Les chiffres comptent les recherches mensuelles sur le marché. Ils montrent combien de personnes cherchent à satisfaire un besoin ; aucun chiffre public n’indique combien de fois ce même besoin est posé aux assistants IA. Utilisez-les pour classer les prompts, pas comme une prévision du trafic IA.
• La formulation est générée ; les chiffres ne le sont pas. Chaque prompt est rédigé pour son besoin, et le même seed peut être regroupé différemment d’une exécution à l’autre : le haut de la liste est en général stable et la fin varie.
• Les recherches rares sont écartées. Les termes recherchés moins de 10 fois par mois n’ont pas de demande déclarée et n’ajoutent rien à un prompt.
• Les parts comparent les besoins au sein d’une même graine. demandShare montre comment la demande de recherche autour de cette graine se répartit entre besoins, thèmes et personas. Ce n’est pas une part des conversations IA, et les parts de graines différentes ne s’additionnent pas.

​

Erreurs et facturation

• 12 crédits par tâche terminée. Une tâche en échec libère sa réservation de crédits.
• 422 VALIDATION_ERROR — un champ est hors limites, brandAliases ou brandDescription a été envoyé sans brand, ou monitorSize × le nombre de monitorEngines dépasse 200.
• 422 REGION_UNSUPPORTED — country n’est ni KR ni US.
• Le champ error d’une tâche échouée commence par son code. NO_SEARCH_DEMAND signifie qu’aucune demande de recherche n’a été trouvée pour le seed ni pour ce qui s’y rapporte ; essayez un terme plus large ou plus courant. NO_RELATED_SEARCHES signifie que le seed lui-même est recherché mais que rien de lié ne l’est ; essayez une formulation plus précise que les gens recherchent. Le même seed échoue de la même manière. KEYWORD_DATA_UNAVAILABLE, ANALYSIS_FAILED et ANALYSIS_TIMEOUT sont temporaires ; réessayez peu après.