ブランドモニターとカテゴリモニター
モニターにはmode があります。作成時に設定し、以後は変更できません。保存されるすべての回答の意味を決めるためです。
各回答は届いたときに一度だけ採点します。
- 言及: 自社のエイリアスのいずれかが回答テキストに現れます。
positionは最初に一致した箇所の文字オフセットで、 ブランドがなければnullです。 - 引用: 回答が自社の
domainsのいずれか、またはそのサブドメインのページを引用しています。 - 競合の一致: モニターの競合のうち、同じ回答に現れたもの。
analysis をオンにします。
クイックスタート
1
モニターを作成する
最初の実行はモニターの作成直後に始まります。レスポンスは保存されたモニターを含む
201 です。data.monitor.id を控えておきます。2
回答を待つ
タスクはプランの同時実行数が許す分だけ投入されるため、1回の実行は数秒から数分かけて届きます。
レポートの
health.pending はまだ処理中のタスク数です。0になったらレポートを読んでください。3
レポートを読む
quality を読み、それから stats、brands、opportunities を読みます。各フィールドの説明は
レポートと指標にあります。POST /v1/monitors/{id}/run を呼び出します。
モニターを作成する
POST /v1/monitors(リファレンス)は定義を検証し、アカウントの上限と
照らし合わせて保存し、最初の実行を開始します。呼び出しはその実行が終わる前に 201 を返します。最初の実行を
開始できない場合(たとえば残高不足)でもモニターは作成され、スケジューラーが毎分実行を再試行します。
たとえば、クイックスタートのリクエストは次を返します。
リクエストフィールド
リスト型のフィールドはすべて、JSON配列または改行区切りの文字列1つを受け付けます。各エントリは前後の空白を除去し、 空のエントリは捨て、重複は取り除きます。エンジン
モニターにスケジュールできるのはプロンプト型の回答エンジンです:CHATGPT、GEMINI、PERPLEXITY、GOOGLE
(Google AI Overviews)、AIMODE(Google AI Mode)、NAVER_AI_BRIEF、NAVER_AI_TAB、および既存モニターのために
残している非推奨の名前 NAVER。エイリアス GOOGLE_AIO、GOOGLE_AIMODE、NAVER_AI_MODE は受け付けて、それぞれ
GOOGLE、AIMODE、NAVER_AI_TAB として保存します。エンジン名は大文字と小文字を区別します。GOOGLE_SERP や
CITATION_ANALYSIS などの検索、Webデータ、分析のタスクタイプはスケジュールできません。価格とエンジンごとの詳細は
エンジンカタログにあります。
一部のエンジンに制限されたAPIキーは、そのエンジンを使うモニターだけを作成、更新、実行できます。それ以外は
403 KEY_SCOPE_DENIED を返します。
競合
競合を入力する必要はありません。最初の実行の後、モニターの最近の回答を週に一度読み、自社と同じものを扱い、 2つ以上の回答に登場するブランドを追加します。ブランドモニターは最大15社、カテゴリモニターは25社です。- 見つけた競合は
source: "auto"、自分で挙げた競合はsource: "user"です。読み取りが自分で挙げたものを変更したり 削除したりすることはありません。見つけたブランドが続く2回の読み取りでどちらも見つからなければ外れます。 - 見つけた一覧が変わると、モニターに保存された回答を新しい一覧で採点し直します。そのため、レポート内のすべての
ブランドは同じ回答をもとに測定されます。最後の読み取り時刻は
competitorsReadAtにあります。 - 更新時、
competitorsは自分で挙げた一覧を置き換え、見つけた競合は残します。リクエスト内のsource: "auto"の エントリは無視されるため、GETが返したものをそのまま送り返せます。
名前の照合方法
- 照合は大文字と小文字、文字幅(NFKC)を区別しません。
- ラテン文字の名前は単語単位でのみ一致します。「replicates」は Replicate というブランドの言及ではありません。 名前に接するハングル、かな、漢字、タイ文字は単語の区切りとみなすため、「agoda를」と「ahamoが」は agoda と ahamo の言及です。韓国語、日本語、中国語、タイ語の名前はテキスト内のどこでも一致します。
- 1文字の名前は一致しません。そのようなブランドには長いエイリアスを付けてください。
- 2つの名前が重なる場合は、先に始まるもの、次に長いものが数えられます。「Acme Pro」という競合の中の「Acme」は 競合として数えます。
- リンク先、裸のURL、引用チップは照合前に取り除き、リンクの表示テキストは残します。引用は
citedに数え、 言及には数えません。
何かを測れるプロンプトを書く
- トピックと市場ごとに1つのモニターにします。「おすすめのCRM」と「CRMの価格はどう決めるか」は異なる意図で、 平均すると両方が見えなくなります。
- プロンプトは購入者の言い回しで書き、自社ブランドを決して含めないでください。ブランドを含むプロンプトは常に 言及になるため100%を報告し、何も測りません。プロンプトに競合名を含めるのは問題ありません。
サンプルとエンジン別の周期
AIの回答はセッションごとに変わるため、1件の回答より複数回答の割合のほうが安定します。engineSettings は
エンジンごとに、プロンプトあたりに集める回答数とエンジンを実行する頻度を設定します。
samples: 各実行でプロンプトと地点あたり1〜10件の回答(既定1)。それぞれが独自のセッションの別タスクで、 他のタスクと同じく採点・課金されます。intervalHours: モニターのintervalHoursの倍数で、最大168。エンジンは最初の実行から数えて k 回ごとの実行に 参加し、最初の実行にはすべてのエンジンが参加します。
engineSettings は保存済みの
値を置き換えます。エンジンを外す更新はそのエントリも外し、モニターの intervalHours を変える更新はエンジンの間隔を
新しい値で確認し直します。
位置とグリッド
既定では、すべてのタスクは国全体を対象に質問します。地域ごとの回答を測るには:locationはすべてのプロンプトを1つの地点(10進数の度)から質問します。gridはすべてのプロンプトをcenterを囲む正方形グリッドの各地点から質問します。sizeは一辺の地点数で、 3、5、7、9(9〜81地点)。radiusMetersは100〜50,000で、中心から辺の中点までの距離です。
CHATGPT、GEMINI、GOOGLE、AIMODE だけです。位置またはグリッドを持つモニターに
それ以外のエンジンがあると 400 VALIDATION_ERROR で拒否されます。更新時、location と grid の一方を設定すると
もう一方は消え、null で消去します。地点ごとの回答は
GET /v1/monitors/{id}/gridで読み取ります。
回答ページ
タスクがページを保存した回答は、そのアドレスがdisplay.html に載り、ドロワーがフォントを埋め込んだファイルとして渡します。ページはマークダウンを描き直したものではなく、エンジンの実際の画面です。
モニターの実行はページを求めないため、その回答にページは付きません。それでもどのタスクかがページを残していれば、アドレスはそのタスクから読み戻すので回答から開けます。
コストとスケジュール
1回の実行では、参加するエンジンごとに、プロンプト・地点・サンプルごとに1タスクを作成します。points はグリッドがなければ1です。たとえば12個のプロンプトを CHATGPT(1クレジット)と GOOGLE(1.25クレジット)に
送ると、1回あたり24タスク、27クレジットで、毎日実行すると月約810クレジットです。"CHATGPT": { "samples": 5 } に
すると同じモニターは1回あたり72タスク、75クレジットです。価格はハードコードせず
GET /v1/monitors/capabilities から現在の値を読み取ってください。クレジットの確保と請求の仕組みは
クレジットと上限にあります。
タスクに加えて2つの料金がかかります。
- 競合の読み取り: モニターごとに30日あたり80クレジットで、周期に応じて各実行に分けて請求します(毎日実行する モニターは1回あたり約2.67クレジット、毎週なら18.67クレジット)。実行のタスクがすべて投入されたときに請求するため、 残高不足で止まった実行にはかかりません。
- 回答の分析:
analysis: trueの場合、タスクあたり1クレジットで、分析した回答にだけ請求します。スコア (mentioned、cited、position)は変わりません。回答ごとの結果はGET /v1/monitors/{id}/answers/{taskId}のanswer.analysisにあります。
location または grid を持つモニターは、タスクごとに1クレジットが加算されます。
レポート、ソース、回答、結果の読み取りは無料です。
スケジュールの動作:
- 実行は一度に集中しません。 タスクはプランの同時実行数とエンジンのキューが許す分だけ投入されます。スケジューラーは 毎分止まったところから続け、エンジンごとに1件ずつ交互に投入し、異なるアカウントのモニターも順番に処理します。 親アカウントとそのサブアカウントは1つの順番を共有します。
- 実行は間隔内に収まる必要があります。 あるエンジンのタスクを、そのエンジンが次に実行されるまでに投入しきれない
場合、作成と更新は収まる最短の間隔を示して
400 VALIDATION_ERRORを返します。1間隔が経過してもまだ投入中の実行は 締め切られ、残りのタスクは送信されません。 - 逃した実行は再実行しません。
nextRunAtは次の実行の予定時刻です。一時停止したモニターを再開するかintervalHoursを変えると、次の実行はその時点から1間隔後に予定されます。
Capabilities
GET /v1/monitors/capabilities(リファレンス)は、アカウントについて
次を返します: スケジュール可能な各エンジンと creditsPerTask、analysisCreditsPerTask、placeCreditsPerTask、アカウントの limits、
modes、指標の定義(metrics)、スケジュールの計算式、変化イベントの種類。副作用はなく無料です。プログラムで
モニターを作成する前に呼び出してください。
プロンプトを選ぶ
ブランド情報からプロンプトを提案する
POST /v1/monitors/suggest(リファレンス)は、country の購入者が
尋ねるような言い回しで最大12個の候補プロンプトを返します。何も保存せず、クレジットも消費しません。
429 RATE_LIMITED を返します。モデルがブランドを拒否した場合は
400 SUGGEST_FAILED、提案サービスが失敗した場合は 502 SUGGEST_FAILED、設定されていない場合は
503 SUGGEST_FAILED を返します。
検索需要からプロンプトをリサーチする
POST /v1/monitors/research(リファレンス)は
Prompt Research のリクエストボディを受け取り、同じ14クレジットで、同じ結果を
アカウントが所有するタスクとして返します。
data.task にキューに入ったタスクを、data.credits と data.replayed とともに返します。結果は
data.task.id を使って GET /v1/async/task/{id} で読み取ります(非同期タスクを参照)。
その後、prompts[].prompt を順番どおりに prompts としてモニターを作成します。カテゴリモニターでは、調査結果にコアが
2つ以上あれば各プロンプトの core を promptTopics のエントリに、brands[].brand を competitors に使います。
モニターを作成するまで何も保存されません。
1回の実行でキューに入れられるタスクはアカウントの tasksPerRun の上限までで、エンジンごとにプロンプト数 × 地点数 ×
samples で数えます。作成するモニターに合わせて limit を決めてください。
調査結果からモニターを作るを参照してください。
カテゴリモニター
カテゴリモニターは、エンジンがある市場について挙げるブランドを順位付けします。プロンプトはpromptTopics で
サブ分野ごとにまとめます。
aliases、domains、alertBelowPct は空にする必要があり、値を送ると
400 VALIDATION_ERROR を返します。アラートもありません。GET /v1/monitors での stats.mentioned と stats.cited は
常に 0 で、一覧には直近30日に最も多く挙げられたブランド leader が加わります。レポートの説明は
カテゴリレポートにあります。スケジュール、コスト、ソース、回答、結果、
変化イベントはブランドモニターと同じように動作しますが、カテゴリモニターが送るのは monitor.source.first_cited
イベントだけです。
更新時、prompts を編集すると、外したプロンプトの promptTopics エントリも外れます。それらのプロンプトが集めた
回答はランキングに残ります。
モニターを管理する
GET /v1/monitors/{id} の旧形式の期間サマリーは互換性のために残しています。数値には
/analytics を使ってください。旧サマリーはプロンプトとエンジンごとの最新回答の全期間行列を
期間別の数字に混ぜ、ソースをドメイン12件・ページ20件で切り詰め、その shareOfVoice は各ブランドをすべての回答に
対して数えるため、シェアの合計が100を超えることがあります。
他のアカウントのモニターは 403 ではなく 404 NOT_FOUND を返します。
モニターを更新する
PATCH は作成時フィールドの任意の部分集合を受け取り、結果全体を同じ上限で検証します。省略したフィールドは値を
保持します。
enabled: falseでモニターを一時停止し、enabled: trueで再開します。次の実行は今から1間隔後です。 一時停止はレポートにpausesとして現れます。alertBelowPctを変更するとアラートが再び有効になります。- エイリアス、ドメイン、競合の変更は、それ以降に採点される回答に影響します。保存済みの回答は採点時の定義を保持する ため、レポートは変更をまたぐ比較を保留します(レポートと指標を参照)。
モニターを今すぐ実行する
POST /v1/monitors/{id}/run は次の実行を即座に予定し、スケジューラーが約1分以内に開始して data.queued: true を
返します。この実行は定期実行と同じく課金されます。その実行がまだ予定中の間に再度呼び出しても、2回目の実行は
作成されません。
キューに入れる前に、競合の読み取りと分析のクレジットを含めて残高が実行をまかなえるかを確認します。足りなければ
details.needed と details.available を含む 402 INSUFFICIENT_CREDITS を返します。月間クレジット上限を超えた
サブアカウントは 429 SUB_ACCOUNT_CREDIT_LIMIT を受け取ります。一時停止中のモニターは 404 NOT_FOUND を返すので、
先に再開してください。
レポートを共有する
1つのモニターのレポートをhttps://querying.ai/<slug> で公開できます。共有レポートは分析、ソース、引用、結果、回答を
表示し、設定、アラート、実行の操作、アカウントのタスク状態は決して表示しません。
GET /v1/monitors/{id}/share(リファレンス)は現在の状態 access、slug、
locale、url を返し、スラッグが未設定なら suggestedSlug も返します。
PUT /v1/monitors/{id}/share(リファレンス)で変更します。
access を PRIVATE にするとレポートは非公開になりますがスラッグは保持されるため、共有を再びオンにすると同じ
アドレスを再利用します。
エージェントからモニターを使う
MCPサーバーはモニターをツールとして提供します:get_monitor_capabilities、list_monitors、
get_monitor、create_monitor、update_monitor、delete_monitor、run_monitor、
get_monitor_analytics、get_monitor_sources、get_monitor_results、get_monitor_answer、
suggest_monitor_prompts、get_monitor_alerts、test_monitor_alert。各ツールは自分のキーでAPIを1回呼び出します。
エージェントやスクリプト向けの実践的な手順:
GET /v1/monitors/capabilities: 何かを消費する前に、エンジン、価格、上限を読みます。GET /v1/monitors: そのトピックと市場のモニターを再利用するか、作成します。POST /v1/monitors/suggestから 始めても構いません。POST /v1/monitors/{id}/run: 次の定期実行より前に回答が必要な場合だけ実行します。GET /v1/monitors/{id}/analytics?days=30: 数字の前にqualityを読み、health.pendingが0になるまで待ちます。GET /v1/monitors/{id}/sources?days=30&groupBy=page:nextCursorを最後までたどります。GET /v1/monitors/{id}/answers/{taskId}: 行動する前に、opportunitiesの先頭項目の裏にある回答を開きます。GET /v1/monitors/{id}/results?since=...&until=...&format=csv: 同じ期間をエクスポートし、x-next-cursorが 空になるまでたどります。
上限
契約アカウントとは、同時実行数の上限を個別に取り決めたアカウントです。次の上限はすべてのアカウントに適用されます。
レポート、ページサイズ、保持期間の上限は、それを使うページに記載しています:
レポートと指標、ソースと回答、
イベントとアラート。
エラー
エラーのエンベロープは他と同じです(エラーを参照)。モニター固有のコード:次のステップ
レポートと指標
/analytics の契約と、各数字の意味。ソースと回答
引用されたページ、各スコアの裏にある回答、エクスポート。
イベントとアラート
回答が変わったときのWebhookと、言及率のメールアラート。
Prompt Research
追跡する価値のあるプロンプトを検索需要から見つけます。