Prompt Research

주제 하나를 보내면 사람들이 그 주제로 AI 어시스턴트에게 물을 질문을, 그 필요를 매달 몇 명이 검색하는지 순으로 돌려줍니다. 그중 GEO 모니터가 추적할 세트도 넣을 순서대로 골라 줍니다. 모니터 프롬프트를 고르고, 같은 분야에서 어떤 경쟁 브랜드가 수요를 모으는지 볼 때 씁니다.

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개이고 모니터와 같은 이름을 씁니다: `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`와 같습니다.

결과

선크림 실행 결과에서 몇 항목만 남긴 것입니다.

{
  "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입니다.

브랜드가 답하는 프롬프트를 앞에 두려면 브랜드를 설명하세요.

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은 일시적인 실패이니 잠시 후 다시 시도하세요.

시작하기

핵심 개념

엔진

Source Influence

GEO 모니터링

마이그레이션

Prompt Research

Payload

결과

`prompts[]`, 수요가 큰 순서

`monitorSet`

`topics[]`, `personas[]`

`brands[]`

그 밖의 필드

결과를 올바르게 읽기

오류와 과금

​Payload

​결과

​prompts[], 수요가 큰 순서

​monitorSet

​topics[], personas[]

​brands[]

​그 밖의 필드

​결과를 올바르게 읽기

​오류와 과금

Payload

결과

`prompts[]`, 수요가 큰 순서

`monitorSet`

`topics[]`, `personas[]`

`brands[]`

그 밖의 필드

결과를 올바르게 읽기

오류와 과금