> ## 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

> The questions people ask AI assistants about a topic, ranked by the monthly search demand behind each one

Send a topic and get back the questions people would ask an AI assistant about it,
ranked by how many people search for that need each month, and the set of them a
[GEO monitor](/monitors) should track, in the order to add them. Use it to choose a
monitor's prompts and to see which competitor brands draw demand in the same space.

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

The call returns a queued task. Poll `GET /v1/async/task/:id`, or supply
`webhook.url` when submitting; the task reports `taskType: "PROMPT_RESEARCH"` and
usually completes in 30–60 seconds. Do not submit it through `POST /v1/async/task`;
use this endpoint.

## Payload

| Field | Required | Notes |
| - | - | - |
| `seed` | yes | The topic: 1–30 characters of letters, digits and single spaces, such as `선크림` or `무선청소기`. A short product or category term works best; a sentence finds nothing. |
| `country` | yes | `KR` (South Korea) or `US` (United States). Any other value is rejected with `422 REGION_UNSUPPORTED`. Prompts are written in the market's language: Korean for `KR`, English for `US`. |
| `limit` | no | Prompts to return, 1–50. Default 20. |
| `exclude[]` | no | Up to 20 terms of 1–30 characters. A prompt containing one is left out. Use it for a subtopic you do not want; put your own brand in `brand`. |
| `monitorSize` | no | Prompts in `monitorSet`, 1–50. Default 20. |
| `monitorEngines[]` | no | The engines your monitor will run, up to 12, named as in [monitors](/monitors): `CHATGPT`, `GEMINI`, `PERPLEXITY`, `GOOGLE`, `AIMODE`, `NAVER_AI_BRIEF`, `NAVER_AI_TAB`. A monitor runs at most 200 prompt × engine tasks at a time, so when `monitorSize` × the number of engines exceeds 200 the request is rejected with `422 VALIDATION_ERROR` on `monitorSize`. It does not change the result. |
| `brand` | no | Your brand: 1–80 characters with at least two letters or digits; punctuation is allowed. Prompts containing it are left out, as with `exclude`. |
| `brandAliases[]` | no | Up to 10 other names or spellings of your brand, left out the same way. Requires `brand`. |
| `brandDescription` | no | Up to 500 characters on what your brand sells and to whom. Requires `brand`. Each prompt then gets a `fit`, and `monitorSet` favors the prompts your brand answers. |
| `idempotencyKey`, `webhook` | no | Same as [`POST /v1/async/task`](/api-reference/create-task). |

## Result

From a 선크림 run, trimmed to a few entries:

```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[]`, highest demand first

* `prompt` — the question, in the market's language, as a person would ask an AI
  assistant. It never names a brand: a prompt that names one would find that brand
  in every answer.
* `topic` — the broader subtopic the need belongs to. Prompts on one subtopic share the label; `topics[]` sums them.
* `persona` — who is asking, when the searches name an audience, condition or situation (men, parents of babies, oily skin); `null` otherwise.
* `intent` — `informational` (how, what, why), `commercial` (choosing, comparing,
  recommending) or `transactional` (price, where to buy).
* `funnelStage` — `awareness` (learning about the need or category), `consideration` (comparing options), `purchase` (price, where to buy) or `post_purchase` (using what they bought).
* `brandMentions` — whether a good answer to the prompt names brands, products or providers: `likely` (it recommends, ranks or compares options), `sometimes` (it explains, usually with example products) or `rarely` (it explains a concept, method or usage without products).
* `fit` — only when you send `brandDescription`: `core` (the description says your brand offers what the prompt asks for), `related` (anything the description does not mention) or `none` (the description rules it out, such as another audience or product).
* `monthlySearchVolume` — monthly searches for the need behind the prompt.
* `demandShare` — this prompt's share of the demand behind every usable prompt found, from 0 to 1.

### `monitorSet`

The prompts a monitor should track, in the order to add them, chosen from every
usable prompt found, including those past `limit`. The set favors prompts many people
ask whose answers give a monitor something to measure, spread across topics and
personas. Each entry has the fields of a
`prompts[]` entry plus `rank`, starting at 1. `coverage` says how much of the
research the set holds:

* `demandShare` — the chosen prompts' share of the searches behind every usable
  prompt found, from 0 to 1.
* `topics`, `personas` — how many of the topics and personas found the set covers,
  as `covered` out of `total`.

How the set behaves:

* A prompt with `fit` `none` is never picked, so the set can hold fewer than
  `monitorSize` prompts.
* `monitorSize` only cuts one order: the first 12 prompts of a 20-prompt set are the
  12-prompt set, so growing a monitor keeps the prompts it already tracks.
* A monitor runs at most 200 prompt × engine tasks at a time. Send `monitorEngines`
  with the engines your monitor will run, and a `monitorSize` that would not fit is
  rejected when you submit: with five engines, `monitorSize` can be at most 40.

To favor the prompts your brand answers, describe your brand:

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

The description is judged as written, so a one-line description leaves most prompts
`related`. To keep a subtopic out of the set, `exclude` is more reliable.

### `topics[]` and `personas[]`

Demand summed by topic and by persona over every usable prompt found, including those past `limit`, highest first. Each entry has `monthlySearchVolume`, `demandShare` and `promptCount`. Prompts without a persona are left out of `personas[]`.

### `brands[]`

Brands, manufacturers and product lines people search for in this space, with their
monthly searches. Their demand stays out of `prompts` because prompts do not name
brands.

### Other fields

* `seedMonthlySearchVolume` — monthly searches for the seed itself; `null` when there
  is no count for it.
* `promptsFound` — usable prompts before `limit` was applied.
* `demandSource` — the period the numbers cover, and `fetchedAt`. `KR`: `last_30_days`. `US`: `monthly_average_last_12_months`, so a seasonal term reads lower at its peak than that month's searches.

## Reading the result correctly

* **Search demand is not AI conversation volume.** The numbers count monthly
  searches in the market. They show how many people look for a need; no public count
  exists of how often the same need is asked of AI assistants. Use them to rank
  prompts, not as a forecast of AI traffic.
* **The wording is generated; the numbers are not.** Each prompt is written for its
  need, and the same seed can be grouped differently on another run: the top of the
  list is usually stable and the tail varies.
* **Rare searches are left out.** Searches made fewer than 10 times a month carry no
  reported demand and add nothing to a prompt.
* **Shares compare needs within one seed.** `demandShare` tells you how the search demand around this seed divides between needs, topics and personas. It is not a share of AI conversations, and shares from different seeds do not add up.

## Errors and billing

* 12 credits per completed task. A failed task releases its hold.
* `422 VALIDATION_ERROR` — a field is out of range, `brandAliases` or `brandDescription` came without `brand`, or `monitorSize` × the number of `monitorEngines` exceeds 200.
* `422 REGION_UNSUPPORTED` — `country` is not `KR` or `US`.
* A failed task's `error` starts with its code. `NO_SEARCH_DEMAND` means no search
  demand was found for the seed or anything related to it; try a broader or more
  common term. `NO_RELATED_SEARCHES` means the seed itself is searched but nothing
  related to it is; try a more specific phrase people search for. The same seed
  fails the same way again. `KEYWORD_DATA_UNAVAILABLE`, `ANALYSIS_FAILED` and
  `ANALYSIS_TIMEOUT` are temporary; retry shortly.