> ## 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 监测](/zh/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[]` | 否 | 最多 20 个 1–30 字符的词。包含其中任一词的提示词会被剔除。可用于排除不需要的子主题；自家品牌请填在 `brand` 中。 | | `monitorSize` | 否 | `monitorSet` 中的提示词数量，1–50，默认 20。 | | `monitorEngines[]` | 否 | 你的监测将运行的引擎，最多 12 个，名称与[监测](/zh/monitors)相同：`CHATGPT`、`GEMINI`、`PERPLEXITY`、`GOOGLE`、`AIMODE`、`NAVER_AI_BRIEF`、`NAVER_AI_TAB`。一个监测一次最多运行 200 个提示词 × 引擎任务，所以当 `monitorSize` × 引擎数超过 200 时，请求会以 `monitorSize` 上的 `422 VALIDATION_ERROR` 被拒绝。它不影响结果。 | | `brand` | 否 | 你的品牌：1–80 个字符，至少包含两个字母或数字，可以带标点。包含它的提示词会像 `exclude` 一样被剔除。 | | `brandAliases[]` | 否 | 品牌的其他名称或写法，最多 10 个，以同样方式剔除。需要同时提供 `brand`。 | | `brandDescription` | 否 | 用不超过 500 个字符说明品牌向谁销售什么。需要同时提供 `brand`。提供后每个提示词都会带上 `fit`，`monitorSet` 会优先选择你的品牌能回答的提示词。 | | `idempotencyKey`、`webhook` | 否 | 与 [`POST /v1/async/task`](/zh/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` 只是截断同一个顺序：20 个一组的前 12 个就是 12 个一组，所以扩大监测时，已经在追踪的 提示词不会被换掉。 * 一个监测一次最多运行 200 个提示词 × 引擎任务。用 `monitorEngines` 传入你的监测将运行的引擎，放不下的 `monitorSize` 会在提交时被拒绝：有五个引擎时，`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" }' ``` 描述会按字面判断，只写一句话的描述会让大多数提示词成为 `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`，因此季节性词在旺季的数值会低于当月实际搜索量。 ## 正确解读结果 * **搜索需求不等于 AI 对话量。** 数字是该市场的月搜索量，只说明有多少人在寻找某个需求；同一需求被问 AI 助手的频率没有公开统计。请用它给提示词排序，不要当作 AI 流量预测。 * **文字是生成的，数字不是。** 每条提示词都针对其需求撰写，同一种子词在不同运行中的归类方式可能不同：列表前部通常稳定，尾部会变化。 * **低频搜索会被排除。** 月搜索少于 10 次的词没有可报告的需求，不会计入提示词。 * **比例只用于同一种子内的比较。** `demandShare` 显示该种子周边的搜索需求如何分布在需求、主题和人群之间。它不是 AI 对话份额，不同种子的比例不能相加。 ## 错误与计费 * 每个完成的任务消耗 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` 是暂时性错误，请稍后重试。