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

# GEOモニタリングAPI: ブランドの言及と引用

> プロンプトセットを定期実行し、分母が明示されたひとつのレポート契約を読み、すべての数字の裏にある回答をエクスポートします。

モニターは保存したプロンプトセットをスケジュールに従って繰り返し実行し、得られたAI回答を自社ブランドと
競合について採点します。このページはAPI契約です。モニターの設定方法、各数字の意味、その裏にあるソースの
読み方、元の回答のエクスポート方法を扱います。同じデータをダッシュボードで見るには
[プロダクトガイド](https://querying.ai/ja/monitors)から始めてください。

このページのキー、id、ブランド、プロンプトはすべて例です。実際の認証情報や実際のモニターはありません。

## モニターとは

モニターは**ひとつの市場を対象にした名前付きのプロンプトセット**です。プロンプトの一覧、送信先のエンジン、
「自社ブランド」を意味するエイリアス、任意で自社ドメインと数社の競合、国、実行間隔で構成されます。
スケジュール実行ごとに、プロンプト × エンジンの数だけ通常の非同期タスクを送信し、完了した回答は一度だけ
採点して保存します。

採点は意図的に狭く、データは保存した以上のことには答えられません。

* 回答テキストにブランドのエイリアスが現れるかとその文字オフセット、回答が登録済みの自社ドメインのいずれかを
  引用したか、設定した競合のどれが同じ回答に現れたかを記録します。
* 感情スコアや市場シェアの推定値は生成**しません**。順位は、回答が挙げたブランドの中での位置であり、下のカテゴリ
  モニターのブランドランキングがその例です。

### 競合は自動で見つけます

競合を入力する必要はありません。モニターの最初の実行が終わると、最近の回答を言語モデルで読み、自社ブランドと同じものを
扱い、2つ以上の回答で名前が挙がったブランドを最大15社まで残します。この読み取りは30日ごとに繰り返されるため、新しい競合は
加わり、言及されなくなった競合は外れます。

* 見つけた競合は `source: "auto"`、自分で追加した競合は `source: "user"` です。自分で追加したものを読み取りが変更したり
  削除したりすることはありません。
* 見つけた一覧が変わると、モニターに保存された回答を新しい一覧で数え直します。そのため、レポート内のすべてのブランドは
  同じ回答をもとに測定されます。最後の読み取り時刻はモニターの `competitorsReadAt` にあります。
* ラテン文字の名前は単語単位で一致させます。たとえば「replicates」はブランド Replicate の言及として数えません。

### モニターセットは意図をもって分ける

モニターが異なればトピックや市場が異なり、レポートも別です。それぞれ独自の期間、採点定義、スケジュールを
持ちます。2つの習慣が役立ちます。

* トピックと市場ごとに1つのモニターにして、レポートのコホートを比較可能に保ちます。「おすすめのCRM」と
  「CRMの価格はどう決めるか」を1つのセットに混ぜると、異なる2つの意図が1つの数字に平均されます。
* プロンプトは購入者の言い回しで書き、自社ブランドを決して含めないでください。ブランドを含むプロンプトは常に
  言及と判定され、永遠に100%を報告して何も測りません。競合名は問題なく、最も有用なプロンプトになることも
  多いです。

## カテゴリモニター: 市場のブランドを順位付けする

ブランドモニターはひとつのブランドを追跡します。**カテゴリモニター**は市場を追跡します。カテゴリ名を決め、質問を
サブ分野ごとにまとめると、レポートはエンジンが回答で挙げたブランドを順位付けします。モニターを作成するときに
`"mode": "CATEGORY"` を指定します。`mode` の既定値は `BRAND` で、保存されるすべての行の意味を決めるため、
モニターの作成後は変更できません。

```bash theme={null}
curl -X POST "$BASE/v1/monitors" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Sunscreen market",
    "mode": "CATEGORY",
    "category": "Sunscreen",
    "engines": ["CHATGPT", "GEMINI"],
    "prompts": ["best sunscreen for sensitive skin", "best sunscreen for kids"],
    "promptTopics": {
      "best sunscreen for sensitive skin": "Sensitive skin",
      "best sunscreen for kids": "Kids"
    },
    "competitors": [{ "name": "Supergoop" }, { "name": "La Roche-Posay", "aliases": ["LRP"] }],
    "country": "US",
    "intervalHours": 24
  }'
```

| フィールド | カテゴリモニターでは |
| - | - |
| `category` | 必須、1〜80文字。購入者が呼ぶ市場の名前。 |
| `promptTopics` | プロンプト(正確なテキスト)をサブ分野に対応付けます。サブ分野は最大30個で、名前は各60文字以内。エントリのないプロンプトはカテゴリ全体を対象にします。 |
| `competitors` | 順位付けするブランド: 自分で挙げる最大25社。最初の実行が終わると、毎月の読み取りが回答で挙げられたブランドをさらに最大25社加えます。 |
| `aliases` · `domains` · `alertBelowPct` | 空のままにします。カテゴリモニターには自社ブランド、自社ドメイン、アラートがないため、値を送ると `400 VALIDATION_ERROR` が返ります。 |

スケジュール、コスト、期間、フィルター、`quality`、ソース、引用、結果、回答はブランドモニターと同じように動作します。
カテゴリモニターにアラートはないため、`POST /v1/monitors/{id}/alerts/test` は `400` を返します。

### レポートが順位付けするもの

`GET /v1/monitors/{id}/analytics` はカテゴリ用のビューを返します。`stats` と `previous` は `runs`、`named`(追跡
ブランドを1つ以上挙げた回答の数)、`namedRate` を持ち、`changes.namedRatePp` はポイント差で、`category` オブジェクトが
順位を持ちます。

| フィールド | 内容 |
| - | - |
| `category.brands` | 回答が挙げたすべての追跡ブランド。挙げた回答が多い順に、`rank`、`mentions`、`sampleSize`、`mentionRate`、`shareOfVoice`、直前の期間との差。 |
| `category.topics` | サブ分野ごとの1行(`topic: null` はカテゴリ全体)。`runs`、`namedRate`、最も多く挙げられた3ブランド。 |
| `category.engines` | エンジンごとの1行と、そのエンジンが最も多く挙げる3ブランド。 |
| `category.series` | UTC日ごとの、上位5ブランドの割合。 |
| `category.prompts` | プロンプトごとの1行。上位ブランドとエンジン別のセル。各セルには、その裏にある回答を開く `evidenceTaskId` があります。 |

* **`rank`** は、ブランドを挙げた回答の数で順序付けします。これらの回答が挙げたブランドの中での位置です。どの回答にも
  挙げられなかったブランドの `rank` は `null` です。
* **ブランドの `mentionRate`** は、そのブランド自身の `sampleSize`(ブランドが一覧にあった間に採点された回答)で割ります。
  今日追加したブランドは今日から測定されます。
* **`shareOfVoice`** は期間内の `100 × そのブランドの言及数 / 追跡ブランドの言及の合計` なので、ひとつの期間のシェアを
  足すと100になります。
* `GET /v1/monitors` はカテゴリモニターごとに `leader`(最も多く挙げられたブランドとその割合)を加えます。`mentioned` と
  `cited` は常に `0` です。
* `GET /v1/monitors/{id}/answers/{taskId}` は `mode`、空の `aliases`、追跡ブランドの一覧である `competitors` を返します。

### 検索需要からプロンプトをリサーチする

`POST /v1/monitors/research` は [Prompt Research](/ja/research/prompt-research) のリクエストボディを受け取り、同じ12クレジットで、
同じ結果を返します。タスクはアカウントとして送信されます。キューに入ったタスクは `GET /v1/async/task/{id}` で読み取ります。id はレスポンスの `data.task.id` です。

```bash theme={null}
curl -X POST "$BASE/v1/monitors/research" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{ "seed": "sunscreen", "country": "US", "monitorSize": 10, "monitorEngines": ["CHATGPT", "GEMINI"] }'
```

`monitorSet.prompts` を `prompts` に、各プロンプトの `topic` を `promptTopics` のサブ分野に、`brands[].brand` を
`competitors` に使います。ダッシュボードの**リサーチを実行**ボタンが同じ処理を行い、フォームを埋めます。モニターを作成
するまで、何も保存されません。

## コストとスケジュール

1回の実行で、プロンプトごと・エンジンごとに1タスクを各エンジンの公開クレジット価格でキューに入れます。
スケジュールはモニターを一時停止または削除するまで繰り返すため、作成時に選んでいるのは継続的なコストです。

```text theme={null}
credits per run  = prompts × sum(credits for each engine)
credits / month  ≈ credits per run × (24 × 30) / intervalHours
```

たとえば12個のプロンプトを ChatGPT(2クレジット)と Gemini(1クレジット)に送ると、1回あたり24タスク、
36クレジットで、毎日実行すると月約1,080クレジットです。価格はハードコードせず、capabilities エンドポイントから
読み取ってください。

スケジュールに頼る前に知っておくべき性質が2つあります。

* 実行は一度に集中**しません**。タスクはプランの同時実行数とキューが許す分だけ投入されるため、無料プランの上限を
  超える実行は破棄されず数分かけて届きます。進行中の実行はレポートの `health.pending` で確認してください。
* 次の期間は保証ではなく時刻です。`nextRunAt` は実行の予定時刻で、1週間一時停止したモニターは逃した実行を
  まとめて行わず、再開した時点から1間隔後に再開します。

競合の自動分析には、モニターごとに月100クレジットが加わり、実行間隔に応じて各実行に分けて請求されます。毎日実行する
モニターは1回あたり約3クレジット、毎週なら約23クレジットです。実行のタスクがすべて投入された後に請求されるため、
残高不足で止まった実行には請求されません。

## エンドポイント

| メソッドとパス | 得られるもの |
| - | - |
| `GET /v1/monitors/capabilities` | エンジンとクレジット価格、上限、指標の定義、スケジュールの費用計算。副作用のない軽い読み取りです。 |
| `GET /v1/monitors` | 自分のモニターと、それぞれの30日集計。 |
| `POST /v1/monitors` | モニターを作成して開始します。 |
| `GET /v1/monitors/{id}` | レガシーの期間詳細。代わりに `/analytics` を使ってください。これはフィルターなしの全期間セル行列を期間別の数字に混ぜ、引用をドメイン12件・ページ20件で切り詰めます。 |
| `PATCH /v1/monitors/{id}` | フィールドを更新するか、`enabled` で一時停止と再開をします。 |
| `DELETE /v1/monitors/{id}` | モニターと採点履歴を削除します。 |
| `POST /v1/monitors/{id}/run` | 次の実行を今に前倒しします。通常の実行と同じくクレジットを消費します。 |
| `GET /v1/monitors/{id}/analytics` | **レポート契約。** 1つのコホート、1つのフィルターセット、すべてのセクション。 |
| `GET /v1/monitors/{id}/sources` | 同じ期間の引用ドメインまたはページ、ページネーション付き。 |
| `GET /v1/monitors/{id}/citations` | 上位ドメインとページの日別引用数。ダッシュボードの引用チャートが使うデータです。 |
| `GET /v1/monitors/{id}/results` | 採点済みの行そのものをJSONまたはCSVで、フィルターとカーソル付き。 |
| `GET /v1/monitors/{id}/answers/{taskId}` | 1行の裏にある保存済みの回答。 |
| `GET /v1/monitors/{id}/prompt` | 1つのプロンプトの詳細: 時系列、ソース、最近の行。 |
| `GET /v1/monitors/{id}/alerts` · `POST .../alerts/test` | アラートのしきい値、ラッチ状態、配信履歴。テストメールをキューに入れます。 |
| `POST /v1/monitors/suggest` | ブランド情報から作った候補プロンプト。何も保存せず、タスククレジットも消費しません。 |
| `POST /v1/monitors/research` | モニター用のプロンプトリサーチ: [Prompt Research](/ja/research/prompt-research) と同じリクエスト、料金、結果を、アカウントとして送信します。 |

いずれもAPIの他の部分と同じBearerキーを使います([認証](/ja/authentication)を参照)。他のアカウントが所有する
モニターは `403` ではなく `404` を返します。

## モニターを作成する

```bash theme={null}
curl -X POST "$BASE/v1/monitors" \
  -H "Authorization: Bearer $QUERYING_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Earbud brand tracking",
    "engines": ["CHATGPT", "GEMINI"],
    "prompts": ["best wireless earbuds for commuting", "are cheap earbuds worth it"],
    "aliases": ["Acme Audio", "Acme"],
    "domains": ["example.com"],
    "competitors": [{ "name": "Sony", "aliases": ["Sony"] }],
    "country": "US",
    "intervalHours": 24
  }'
```

`name`、`engines`、`prompts`、`aliases`、`intervalHours` はブランドモニターで必須で、カテゴリモニターは `aliases` の代わりに `category` を受け取ります。各リストは配列または改行区切りの文字列1つを
受け付け、各エントリは前後の空白を除去し、空行を捨て、重複を取り除きます。`country` はエンジンが回答する市場を
選ぶだけで、プロンプトを翻訳しません。`prompts × engines` は capabilities の `tasksPerRun` 上限以下でなければ
なりません。

エンジンはスケジュール可能なプロンプトサーフェスです: `CHATGPT`、`GEMINI`、`PERPLEXITY`、`GOOGLE`、`AIMODE`、
`NAVER_AI_BRIEF`、`NAVER_AI_TAB`、および非推奨のエイリアス `NAVER`。`GOOGLE_AIO` と `GOOGLE_AIMODE` は受け付けて
`GOOGLE` と `AIMODE` として保存します。`SOURCE_INFLUENCE` などの分析タスクはプロンプトサーフェスではないため、
モニターにスケジュールできません。

一部のエンジンに制限されたキーはそのエンジンだけをスケジュールでき、それ以外は `403 KEY_SCOPE_DENIED` です。
アカウント単位のモニター上限に達すると `409 MONITOR_LIMIT` を返します。

## 実行してからレポートを読む

`POST /v1/monitors/{id}/run` は次の実行を即座に予定し、回答タスクは約1分以内に現れます。この実行は定期実行と
同じく課金され、その期間がまだ予定中の間に呼び出しを再試行しても二重に課金されません。

`GET /v1/monitors/{id}/analytics` は、レポートのすべての部分の拠り所となる契約です。期間は**半開区間でUTC基準**
です。`since` は含み、`until` は含まず、次の2つの方法のどちらかで選びます。

| パラメーター | ルール |
| - | - |
| `days` | `7`、`30`(既定)、`90` のいずれかで、現在時点で終わります。`since`/`until` とは併用できません。 |
| `since` と `until` | 両方を一緒に指定し、**タイムゾーン付き**の完全なISO時刻にします(例: `2026-09-15T00:00:00Z`)。期間は正で、最大90日、未来は不可です。単なる `YYYY-MM-DD` はここでは拒否されます。移植可能な期間を定義できないためです。 |

任意の2つのフィルターが**すべての**セクションに同時に適用されます。`engine`(正規idまたは公開エイリアス)と
`prompt`(完全一致のテキスト、最大2,000文字)です。行はプロンプトのテキストをキーにしているため、後でモニターから
外したプロンプトも引き続き照会できます。

すべてのセクションがその1つのコホートを共有し、前の区間は長さもフィルターもまったく同じなので、同条件で比較できます。

| フィールド | 内容 |
| - | - |
| `window` | `since`、`until`、`previousSince`、`previousUntil`、`timezone`、期間の `bounds` 表記。`previousUntil` は常に今回の期間の `since` です。 |
| `filters` | 適用されたフィルターの解決値: 正規のエンジンid、完全一致のプロンプト、または `null`。 |
| `stats` · `previous` | 今回の期間とその前の区間の件数と比率。 |
| `changes` | パーセントポイントの変化量。比較が妥当でない場合は `null`(下記参照)。 |
| `engineRates` | 同じ比率をエンジン別に。チャートを読まなくても弱いエンジンが分かります。 |
| `series` | UTCの日とエンジンごとの値。`partial` は期間の境界で切れた日を示します。 |
| `brands` | 自社ブランド(`__you__`)と追跡中のすべての競合、言及の多い順。それぞれ独自の `sampleSize` とそれに基づく比率を持ちます。 |
| `voiceSeries` | 同じブランドのUTC日別の値、トレンドライン用。 |
| `prompts` | プロンプト別の合計、言及率の低い順。それぞれエンジン別のセルを持ちます。 |
| `opportunities` | 競合は言及されたのに自社ブランドは言及されなかったセル、取りこぼしの多い順。取り組むべきリストです。 |
| `quality` | サンプルの構成と、数字が語れないことのすべて。 |
| `health` · `healthScope` | まだ個別に見えるタスクの実行状態。別の直近スコープで、分母には含まれません。 |

## 数字の意味

ダッシュボードのパネルに名前を付ける前に読んでください。これらの定義は公開された契約であり、
`GET /v1/monitors/capabilities` が `metrics` として返すため、クライアントは数字の横に表示できます。

* 期間、エンジン別グループ、セル別グループの **`mentionRate`** は `100 × 言及された回答 / 採点された回答` です。
  エンジン別比率の平均ではなく回答数で重み付けするため、忙しいエンジンが静かなエンジンに埋もれません。
  (ブランド自身の比率は独自の分母を持ちます。次で説明します。)
* **`citationRate`** は、登録済みの自社ドメインのいずれかを引用した回答について同じ形で数えます。ドメインを登録
  していなければ引用追跡がオフなので、常にゼロです。
* **ブランドの比率は期間全体ではなく自身の `sampleSize` で割ります。** 自社ブランドは採点されたすべての回答、
  競合はモニターに登録されていた間に採点された回答だけです。今日競合を追加すると、最初のレポートはその競合を
  測った回答だけを扱い、存在前の履歴は不利に数えません。該当する回答がないブランドは0%ではなく
  `mentionRate: null` を報告します。0%は実際に消えたように読めてしまうからです。
* `brands` の **`shareOfVoice`** は、期間内の `100 × そのブランドの言及 / 追跡中の全ブランドの言及` で、1つの期間の
  シェアを合計すると100になります。**これらのプロンプトで収集した回答**の中でブランドを比較する値であり、
  市場シェアでも可視性ランキングでもありません。レガシー詳細エンドポイントの `shareOfVoice` は以前の回答浸透率の
  見方で、各ブランドを収集した回答数に対して数えるため合計が100を超えることがあります。2つを1つのチャートに
  混ぜないでください。
* **`competitorOnly`**(と `opportunities` リスト)は、自社ブランドがなく設定済みの競合を挙げた回答を数えます。
  実際に手を打てるギャップです。
* **比率はゼロではなくnullになり得ます。** 期間に回答がなければ `null`、比率ゼロは回答があったが1つも一致
  しなかったことを意味します。
* **回答なしで完了した観測は「言及なし」として数えます。** 分母に残り、`quality.noAnswerObservations` がその数を
  示します。**失敗した**タスクはすべての比率から除外され `health` にのみ現れます。壊れたエンジンは黙って不在に
  変わるのではなくサンプルを減らし、`quality` がそれを不在として再構成することもありません
  (`historicalFailures` は常に `null`)。
* **誤解を招く変化量は保留します。** 一方の期間に回答がない場合(`insufficient_periods`)、採点コンテキストが
  できる前に採点された行の場合(`legacy_scoring_unknown`)、2つの期間の間で採点定義が変わった場合
  (`scoring_definitions_changed`)は、`changes` とセル別の `mentionRateChangePp` が `null` になり、
  `quality.comparable` は `false` です。過去の行は採点時の定義を保持するため(`quality.scoring`)、エイリアスや
  競合を変えても過去が書き換わることはありません。例外は上で説明した毎月の競合読み取りだけです。
* **サンプルサイズを公開します。** 採点された回答が30未満なら `quality.lowSample` がtrueになり、
  `quality.missingCells` はまだ回答のない設定済みのプロンプト × エンジンのセル数を数え、`quality.partialDays` は
  期間が半分に切ったUTCの日を示します。部分日の件数が少ないのは計算上の結果であり、減少ではありません。

採点済みの行の `position` は、回答テキスト内で最初に現れたエイリアスの**文字オフセット**です。順位ではなく
目立ち具合の代理指標です。ブランドがなければ `null` なので、`0` が「なし」を意味することはありません。

## 回答のソース

`GET /v1/monitors/{id}/sources` は「どのページがこれらのプロンプトを勝ち取っているか」に答えます。レポートと同じ
期間とフィルターを使い、生の引用数ではなく**異なる回答の数**を数えるため、1つの回答で3回引用されたページも
1回と数えます。

| パラメーター | ルール |
| - | - |
| `groupBy` | `domain`(既定、`www.` を除いたホスト)または `page`(ラベル付きの完全なURL)。 |
| `limit` | 1–100、既定20。 |
| `cursor` | 前のレスポンスの `nextCursor` をそのまま渡します。`null` で一覧の終わりです。 |
| `days` / `since`+`until` / `engine` / `prompt` | レポートとまったく同じです。 |

各行には `citations` と `prompts`(どちらも異なる回答の数)、登録済みの自社ドメインを示す `own`、回答エンドポイントで
開ける `evidenceTaskId` があります。ここでは暗黙の上位N件の切り捨てはありません。カーソルをたどれば期間内の
すべてのドメインやページに到達できます。

## 引用の推移

`GET /v1/monitors/{id}/citations` は、ダッシュボードの引用チャートに使われるデータをそのまま返します。
期間全体の日別引用数と、上位のドメインとページごとの日別系列です。保存済みの結果だけを読むため、
クレジットは消費しません。

| パラメータ | ルール |
| - | - |
| `days` | `7`、`30`、`90` のいずれか。既定値は `30`。 |
| `since`+`until` | レポートと同じ、最大 90 日の固定期間。指定すると `days` は表示用のラベルになります。 |
| `engine` / `prompt` | レポートと同じです。 |
| `kind` | `all`(既定値)、`owned`, `editorial`, `pr_wire`, `institution`, `reviews`, `commerce`, `social`, `other`。 |
| `q` | ドメインは名前で、ページは URL で絞り込みます。最大 200 文字。 |
| `offset` | 0–10,000。各リストは 20 件を返します。 |

ここでの引用 1 件は、1 つの回答に現れた 1 つのページです。同じ回答に同じページが 2 回出ても 1 件と数えます。
`/sources` は異なる回答の数を数えるため、数値が異なる場合があります。

| フィールド | 意味 |
| - | - |
| `totals` | 期間全体の `answers`、`citedAnswers`、`citations`、`ownedCitations`。 |
| `days` | 測定された UTC 日ごとの `answers`、`citations`、`ownedCitations`。回答はあるが引用がない日は `citations: 0` で現れ、回答がない日は含まれません。 |
| `domains` / `pages` | 現在の `offset` の上位 20 件。各項目に `kind`、`owned`、`citations`、`answers`、`prompts` と、`{day, citations}` 形式の `daily` 系列があります。`daily` には引用があった日だけが入ります。 |
| `types` | `kind` ごとの引用数とドメイン数。すべての出典が対象です。 |
| `pagination` | `offset`、`limit`、`totalDomains`、`totalPages`。 |

出典のシェアは、その出典の `citations` を `totals.citations` で割った値です。`kind`、`q`、`offset` はリストを
絞るだけで、`totals`、`days`、`types` は常に期間内のすべての出典を対象にします。

```bash theme={null}
curl "$BASE/v1/monitors/$MONITOR_ID/citations?days=30&kind=owned" \
  -H "Authorization: Bearer $QUERYING_API_KEY"
```

## 採点済みの行をエクスポートする

`GET /v1/monitors/{id}/results` は行そのものを返します。データウェアハウスへのロード、週次の報告資料、
スプレッドシートに使ってください。

| パラメーター | ルール |
| - | - |
| `since` · `until` | 半開区間、既定は現在時点で終わる直近30日。`since` は元のエクスポートとの互換のため単なる `YYYY-MM-DD`(`00:00:00Z` として解釈)も受け付けます。レポートエンドポイントは受け付けません。 |
| `engine` · `prompt` | レポートと同じフィルター。 |
| `mentioned` · `cited` | `true`/ `false`。`mentioned=false` が競合ギャップのビューです。 |
| `competitor` | 設定済みの競合名と完全一致。保存された競合リストにその名前を含む回答を残します。 |
| `includeEvidence` | すべての行に `answerText`、`sources`、`scoringContext` を加え、ページサイズの上限を下げます。 |
| `limit` | 1–10,000、既定10,000。`includeEvidence` では既定値と最大値が100です。 |
| `format` | `json`(既定)または `csv`。 |
| `cursor` | 前のレスポンスの `nextCursor`。 |

ページネーションはマイクロ秒精度の `(ranAt, id)` によるキーセット方式なので、同じタイムスタンプを共有する行も
抜けたり重複したりしません。抽出を再現可能にするには、**明示的な `since` と `until` を送り、固定したまま、
`nextCursor` が `null` になるまでたどってください。** ページの間で期間を変えると、行が抜けたり重複したりする
ことがあります。カーソルは不透明な値として扱い、返されたものをそのまま戻すだけで、自分で組み立てないでください。

`format=csv` の場合、レスポンスは `text/csv`(Excel が正しく開けるようBOM付きのUTF-8)になり、CSV本文には置き場所が
ないため、ページネーションの状態はヘッダーに移ります。

| ヘッダー | 意味 |
| - | - |
| `x-next-cursor` | 次のページのカーソル。最後のページでは空です。 |
| `x-result-truncated` | このページが返した以上の行が一致した場合は `true`。 |
| `x-result-since` · `x-result-until` | 解決済みの期間。再開したエクスポートで固定できます。 |

列は `ran_at, monitor, engine, prompt, mentioned, cited, position, competitors, task_id` で、
`includeEvidence=true` のときは `answer_text, sources, scoring_context` が加わります(`sources` と `scoring_context` は
セル内のJSONテキスト)。スプレッドシートの数式として読まれ得るセルは書き込み前に無害化するため、外部のテキストが
シート上で数式に変わることはありません。

## 数字の裏にある回答を読む

`GET /v1/monitors/{id}/answers/{taskId}` は1行分の保存された根拠を返します。

* `answerText`: エンジンが返したままの回答。可能ならmarkdownで、**最大8,000文字**、それより長い場合は末尾に
  省略記号を付けて切り詰めます。
* `sources`: エンジンの順序での引用。それぞれラベルと、引用リスト内での1始まりの位置を持ちます。
* `aliases` と `competitors`: この行の照合対象。言及を鵜呑みにせず確認できます。
* `scoringContext`: 使われた定義そのもの。`version` ハッシュ、採点時刻、`answerPresent`、上のテキストが
  切り詰められた場合の `evidenceTruncated` を含みます。

採点コンテキストが保存される前に採点された行は、`scoringKnown: false` とモニターの現在のエイリアス、`null` の
`evidenceTruncated` を返します。エンジンが回答テキストを返さなかった場合、`answerText` は `null` です。

## この領域のエラー

エンベロープは他と同じです([エラー](/ja/concepts/errors)を参照)。モニタリング固有のコードは次のとおりです。

| コード | ステータス | 発生条件 |
| - | - | - |
| `VALIDATION_ERROR` | 400 | 不正な期間(`days` と `since`/`until` の混用、90日超、タイムゾーンなしの時刻)、不明なエンジン、長すぎるプロンプト、範囲外の `limit`、または集計するには大きすぎるレポート。期間、エンジン、プロンプトを絞ってください。 |
| `MISSING_API_KEY` / `UNAUTHORIZED` | 401 | キーがない、またはこのアカウントのキーではありません。 |
| `KEY_SCOPE_DENIED` | 403 | キーに許可されたエンジンがモニターのエンジンをカバーしていません。 |
| `NOT_FOUND` | 404 | このキーで見えるモニターがない(他人のモニターも同じに見えます)、またはそのタスクidの採点済みの行がありません。 |
| `MONITOR_LIMIT` | 409 | アカウントが既に上限数のモニターを持っています。 |
| `RATE_LIMITED` | 429 | プロンプト提案(20秒に1回、1時間に30回)またはテストアラートメール(モニターごとに5分に3回)。 |
| `SUGGEST_FAILED` | 400 / 502 / 503 | このブランドへのプロンプト提案が拒否された、提案サービスが失敗した、またはこのデプロイで設定されていません。 |

## エージェントと組み合わせる

このページのエンドポイントだけで、エージェントやスクリプトが実行できる実践的な手順です。例示なので、キー、
モニターid、期間は置き換えてください。

1. `GET /v1/monitors/capabilities`: 何かを消費する前に、エンジン、価格、上限を読みます。
2. `GET /v1/monitors`: そのトピックと市場の既存モニターを再利用するか、`POST /v1/monitors` で作成します(先に
   `POST /v1/monitors/suggest` を呼んで候補を編集しても構いません)。
3. `POST /v1/monitors/{id}/run`: 次の予定期間より前に回答が必要なら実行します。
4. `GET /v1/monitors/{id}/analytics?days=30&engine=CHATGPT`: まず `quality`(`comparable`、`lowSample`、
   `missingCells`、`partialDays`)を読み、それから数字を見ます。`health.pending` が落ち着き、
   `quality.sampleSize` が増えなくなるまでポーリングします。
5. `GET /v1/monitors/{id}/sources?days=30&groupBy=page`: `nextCursor` でページをめくり、プロンプトを勝ち取って
   いるページを見つけます。
6. `GET /v1/monitors/{id}/answers/{taskId}`: 何かを決める前に、`opportunities` の先頭項目の裏にある回答を開きます。
7. `GET /v1/monitors/{id}/results?since=...&until=...&includeEvidence=true&format=csv`: 同じ期間をエクスポートし、
   `x-next-cursor` が空になるまでたどります。

同じ操作はエージェント向けの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`)。書き込み系は変更操作として注釈され、`create_monitor` と
`run_monitor` は呼び出し前にクレジットを消費することを明示します。

## 上限

| 上限 | 値 |
| - | - |
| アカウントあたりのモニター | 20 |
| 実行あたりのタスク | 200(`prompts × engines`) |
| モニターあたりのプロンプト | 100 |
| プロンプトの長さ | 2,000文字 |
| ブランドのエイリアス | 20 |
| 登録ドメイン | 20 |
| 競合 | ブランドモニター: 手動で10社、自動で最大15社。カテゴリモニター: 手動で25社、自動で最大25社 |
| カテゴリ名 | 80文字 |
| カテゴリモニターのサブ分野 | 30個、名前はそれぞれ60文字以内 |
| 実行間隔 | 1–168時間 |
| レポート期間 | 90日 |
| 結果ページ | 既定10,000、最大10,000。根拠付きは100 |
| ソースまたは根拠のページ | 100 |

ボリュームを増やす前に[料金](https://querying.ai/ja/pricing)と[エンジンリファレンス](/ja/engines/overview)を確認してください。