> ## 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 > あるトピックについて人々がAIアシスタントに尋ねる質問を、その背後にある月間検索需要の順に トピックを送ると、人々がそのトピックについてAIアシスタントに尋ねるであろう質問を、そのニーズが毎月どれだけ 検索されているかの順に返します。そのうち[GEOモニター](/ja/monitors)で追跡すべきセットも、追加する順に選びます。 モニターのプロンプトを選ぶときや、同じ分野でどの競合ブランドが需要を集めているかを見るときに使います。 ```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" }' ``` 呼び出すとキューに入ったタスクが返ります。`GET /v1/async/task/:id` をポーリングするか、送信時に `webhook.url` を指定してください。タスクは `taskType: "PROMPT_RESEARCH"` と表示され、通常30〜60秒で 完了します。`POST /v1/async/task` では送信せず、このエンドポイントを使ってください。 ## Payload | フィールド | 必須 | 説明 | | - | - | - | | `seed` | はい | トピック。文字、数字、単一の半角スペースからなる1〜30文字です。例: `선크림`、`무선청소기`。短い製品名やカテゴリ名が最適で、文章では何も見つかりません。 | | `country` | はい | `KR`（韓国）または `US`（米国）。ほかの値は `422 REGION_UNSUPPORTED` で拒否されます。プロンプトは市場の言語で書かれます（`KR` は韓国語、`US` は英語）。 | | `limit` | いいえ | 返すプロンプト数。1〜50、既定値は20。 | | `exclude[]` | いいえ | 1〜30文字の語を最大20個。いずれかを含むプロンプトは除外されます。不要なサブトピックを外すときに使います。自社ブランドは `brand` に指定してください。 | | `monitorSize` | いいえ | `monitorSet` に入れるプロンプト数。1〜50、既定値は20。 | | `monitorEngines[]` | いいえ | モニターで実行するエンジン。最大12個で、[モニター](/ja/monitors)と同じ名前を使います: `CHATGPT`、`GEMINI`、`PERPLEXITY`、`GOOGLE`、`AIMODE`、`NAVER_AI_BRIEF`、`NAVER_AI_TAB`。モニターが一度に実行できるのはプロンプト × エンジンで200タスクまでなので、`monitorSize` × エンジン数が200を超えると `monitorSize` に対する `422 VALIDATION_ERROR` で拒否されます。結果は変わりません。 | | `brand` | いいえ | 自社ブランド。1〜80文字で、文字または数字を2つ以上含む必要があります。句読点も使えます。この名前を含むプロンプトは `exclude` と同じように除外されます。 | | `brandAliases[]` | いいえ | ブランドの別名や別表記を最大10個。同じように除外されます。`brand` が必要です。 | | `brandDescription` | いいえ | ブランドが何を誰に売っているかを500文字以内で。`brand` が必要です。指定すると各プロンプトに `fit` が付き、`monitorSet` はブランドが答えられるプロンプトを優先します。 | | `idempotencyKey`, `webhook` | いいえ | [`POST /v1/async/task`](/ja/api-reference/create-task) と同じです。 | ## 結果 선크림 の実行結果を、いくつかの項目に絞ったものです。 ```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[]`（需要の大きい順） * `prompt` — 人がAIアシスタントに尋ねる質問を、その市場の言語で書いたものです。ブランド名は含みません。 ブランドを名指しするプロンプトでは、すべての回答にそのブランドが現れてしまうためです。 * `topic` — そのニーズが属する上位トピック。同じトピックのプロンプトは同じラベルを使い、`topics[]` が合計します。 * `persona` — 検索語が対象、状態、状況を示すときの質問者（男性、乳児の親、脂性肌）。ない場合は `null`。 * `intent` — `informational`（方法・定義・理由）、`commercial`（選択・比較・推薦）、 `transactional`（価格・購入先）。 * `funnelStage` — `awareness`（ニーズやカテゴリを知る段階）、`consideration`（選択肢の比較）、`purchase`（価格・購入先）、`post_purchase`（購入後の使用）。 * `brandMentions` — よい回答がブランド・製品・事業者を挙げるかどうか。`likely`（選択肢を推薦・ランキング・比較する）、`sometimes`（説明が中心だが、たいてい例として製品を挙げる）、`rarely`（概念・方法・使い方を製品なしで説明する）。 * `fit` — `brandDescription` を送ったときだけ付きます。`core`（プロンプトが求めるものをブランドが提供していると説明にある）、`related`（説明に書かれていないもの）、`none`（別の対象や製品だけを扱うなど、説明自体が除外している）。 * `monthlySearchVolume` — このプロンプトが表すニーズの月間検索数。 * `demandShare` — 見つかったすべてのプロンプトの需要のうち、このプロンプトの割合（0〜1）。 ### `monitorSet` モニターで追跡すべきプロンプトを、追加する順に並べたものです。`limit` の外も含め、見つかったすべてのプロンプトから選びます。多く尋ねられ、回答にモニターが測れるものがあるプロンプトを先に置き、トピックとペルソナに分散させます。各項目は `prompts[]` の項目のフィールドに、1から始まる `rank` を加えたものです。`coverage` はセットが調査結果をどれだけ含むかを示します。 * `demandShare` — 見つかったすべてのプロンプトの検索需要のうち、選ばれたプロンプトが占める割合。0〜1。 * `topics`、`personas` — 見つかったトピックとペルソナのうち、セットがカバーする数。`total` 個のうち `covered` 個です。 セットの動作は次のとおりです。 * `fit` が `none` のプロンプトは選びません。そのため、セットが `monitorSize` より小さくなることがあります。 * `monitorSize` は1つの順序を切るだけです。20個のセットの先頭12個が12個のセットなので、モニターを 増やしても、すでに追跡しているプロンプトは外れません。 * モニターが一度に実行できるのはプロンプト × エンジンで200タスクまでです。モニターで実行するエンジンを `monitorEngines` で送ると、収まらない `monitorSize` は送信時に拒否されます。エンジンが5つなら `monitorSize` は最大40です。 自社ブランドが答えられるプロンプトを優先するには、ブランドを説明してください。 ```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" }' ``` 説明は書かれたとおりに判断されます。1行の説明では、ほとんどのプロンプトが `related` になります。特定の サブトピックをセットから外すには、`exclude` のほうが確実です。 ### `topics[]` と `personas[]` `limit` を超えた分も含め、見つかったすべてのプロンプトの需要をトピック別・ペルソナ別に合計したものです。大きい順で、各項目に `monthlySearchVolume`、`demandShare`、`promptCount` があります。ペルソナのないプロンプトは `personas[]` に含まれません。 ### `brands[]` この分野で検索されるブランド、メーカー、製品ラインとその月間検索数です。プロンプトにはブランド名を入れないため、この需要は `prompts` に含めません。 ### その他のフィールド * `seedMonthlySearchVolume` — シード自体の月間検索数。集計値がない場合は `null`。 * `promptsFound` — `limit` 適用前の使えるプロンプト数。 * `demandSource` — 数値の対象期間と `fetchedAt`。`KR` は `last_30_days`、`US` は `monthly_average_last_12_months` です。`US` の数値は直近12か月の平均なので、季節性のある語はピーク時にその月の検索数より低く出ます。 ## 結果を正しく読む * **検索需要はAIでの会話量ではありません。** 数値はその市場での月間検索数です。そのニーズを探す人の多さを示すだけで、同じニーズがAIアシスタントにどれだけ尋ねられているかの公開データはありません。プロンプトの順位付けに使い、AIトラフィックの予測には使わないでください。 * **文面は生成され、数値は生成されません。** 各プロンプトはニーズに合わせて書かれ、同じシードでも実行ごとにまとまり方が変わることがあります。リストの上位は通常安定し、下位は変わります。 * **まれな検索語は除外されます。** 月10回未満しか検索されない語は需要が報告されないため、プロンプトに加算されません。 * **割合は1つのシード内での比較です。** `demandShare` は、このシード周辺の検索需要がニーズ・トピック・ペルソナにどう分かれるかを示します。AI会話のシェアではなく、別のシードの割合とは足し合わせられません。 ## エラーと課金 * 完了したタスク1件につき12クレジットです。失敗したタスクは確保したクレジットを解放します。 * `422 VALIDATION_ERROR` — フィールドの値が範囲外か、`brand` なしで `brandAliases` や `brandDescription` を送ったか、`monitorSize` × `monitorEngines` の数が200を超えています。 * `422 REGION_UNSUPPORTED` — `country` が `KR`、`US` のどちらでもありません。 * 失敗したタスクの `error` はコードで始まります。`NO_SEARCH_DEMAND` は、シードにも関連語にも検索需要が見つからなかったことを意味します。より広い語や一般的な語で再試行してください。`NO_RELATED_SEARCHES` は、シード自体は検索されているものの関連する検索がないことを意味します。実際に検索される、より具体的な表現で再試行してください。同じシードは再送しても同じ結果になります。`KEYWORD_DATA_UNAVAILABLE`、`ANALYSIS_FAILED`、`ANALYSIS_TIMEOUT` は一時的なエラーなので、しばらくしてから再試行してください。