GET /v1/async/task/:id をポーリングするか、送信時に
webhook.url を指定してください。タスクは taskType: "PROMPT_RESEARCH" と表示され、通常30〜60秒で
完了します。POST /v1/async/task では送信せず、このエンドポイントを使ってください。
Payload
結果
선크림 の実行結果を、いくつかの項目に絞ったものです。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です。
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は一時的なエラーなので、しばらくしてから再試行してください。