> ## 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 > Les questions que les gens posent aux assistants IA sur un sujet, classées selon la demande de recherche mensuelle derrière chacune Envoyez un sujet et recevez les questions que les gens poseraient à un assistant IA à son propos, classées selon le nombre de personnes qui recherchent ce besoin chaque mois, ainsi que l'ensemble de ces questions qu'un [moniteur GEO](/fr/monitors) devrait suivre, dans l'ordre où les ajouter. Utilisez-le pour choisir les prompts d'un moniteur et pour voir quelles marques concurrentes captent la demande dans le même domaine. ```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" }' ``` L'appel renvoie une tâche en file d'attente. Interrogez `GET /v1/async/task/:id` ou indiquez `webhook.url` lors de la soumission ; la tâche indique `taskType: "PROMPT_RESEARCH"` et se termine généralement en 30 à 60 secondes. Ne la soumettez pas via `POST /v1/async/task` ; utilisez cet endpoint. ## Payload | Champ | Obligatoire | Notes | | - | - | - | | `seed` | oui | Le sujet : 1 à 30 caractères composés de lettres, de chiffres et d'espaces simples, comme `선크림` ou `무선청소기`. Un terme court de produit ou de catégorie fonctionne le mieux ; une phrase ne trouve rien. | | `country` | oui | `KR` (Corée du Sud) ou `US` (États-Unis). Toute autre valeur est rejetée avec `422 REGION_UNSUPPORTED`. Les prompts sont rédigés dans la langue du marché : coréen pour `KR`, anglais pour `US`. | | `limit` | non | Nombre de prompts à renvoyer, de 1 à 50. 20 par défaut. | | `exclude[]` | non | Jusqu'à 20 termes de 1 à 30 caractères. Un prompt qui en contient un est écarté. Utilisez-le pour un sous-thème que vous ne voulez pas ; indiquez votre propre marque dans `brand`. | | `monitorSize` | non | Nombre de prompts dans `monitorSet`, de 1 à 50. 20 par défaut. | | `monitorEngines[]` | non | Les moteurs que votre moniteur exécutera, jusqu'à 12, nommés comme dans les [moniteurs](/fr/monitors) : `CHATGPT`, `GEMINI`, `PERPLEXITY`, `GOOGLE`, `AIMODE`, `NAVER_AI_BRIEF`, `NAVER_AI_TAB`. Un moniteur exécute au plus 200 tâches prompt × moteur à la fois ; si `monitorSize` × le nombre de moteurs dépasse 200, la requête est rejetée avec `422 VALIDATION_ERROR` sur `monitorSize`. Le résultat n'en dépend pas. | | `brand` | non | Votre marque : 1 à 80 caractères avec au moins deux lettres ou chiffres ; la ponctuation est acceptée. Les prompts qui la contiennent sont écartés, comme avec `exclude`. | | `brandAliases[]` | non | Jusqu'à 10 autres noms ou graphies de votre marque, écartés de la même façon. Nécessite `brand`. | | `brandDescription` | non | Jusqu'à 500 caractères sur ce que vend votre marque et à qui. Nécessite `brand`. Chaque prompt reçoit alors un `fit`, et `monitorSet` privilégie les prompts auxquels votre marque répond. | | `idempotencyKey`, `webhook` | non | Comme pour [`POST /v1/async/task`](/fr/api-reference/create-task). | ## Résultat Extrait d'une exécution pour 선크림, réduit à quelques entrées : ```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[]`, 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` Les prompts qu'un moniteur devrait suivre, dans l'ordre où les ajouter, choisis parmi tous les prompts utilisables trouvés, y compris ceux au-delà de `limit`. L'ensemble privilégie les prompts que beaucoup de gens posent et dont les réponses donnent à un moniteur quelque chose à mesurer, répartis entre thèmes et personas. Chaque entrée a les champs d'une entrée de `prompts[]` plus `rank`, à partir de 1. `coverage` indique quelle part de la recherche l'ensemble contient : * `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`. Comment l'ensemble se comporte : * 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. Pour privilégier les prompts auxquels votre marque répond, décrivez votre marque : ```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 description est jugée telle qu'elle est écrite : avec une seule ligne, la plupart des prompts restent `related`. Pour écarter un sous-thème de l'ensemble, `exclude` est plus fiable. ### `topics[]` et `personas[]` La demande additionnée par thème et par persona sur tous les prompts utilisables trouvés, y compris ceux au-delà de `limit`, du plus élevé au plus bas. Chaque entrée contient `monthlySearchVolume`, `demandShare` et `promptCount`. Les prompts sans persona n'apparaissent pas dans `personas[]`. ### `brands[]` Les marques, fabricants et gammes de produits que les gens recherchent dans cet espace, avec leurs recherches mensuelles. Leur demande reste hors de `prompts`, car les prompts ne nomment pas de marque. ### 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.