> ## 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 모니터](/ko/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개이고 [모니터](/ko/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`](/ko/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`는 제출할 때 거절됩니다. 엔진이
  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": "민감하고 건조한 피부를 위한 순한 무기자차 선크림" }'
```

설명은 쓰인 그대로 판단합니다. 한 줄 설명이면 대부분의 프롬프트가 `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회 미만 검색되는 검색어는 보고되는 수요가 없어 프롬프트에 더해지지
  않습니다.
* **비율은 한 시드 안의 비교입니다.** `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`은 일시적인 실패이니 잠시 후 다시 시도하세요.