モニターレポート: 言及率、シェア・オブ・ボイス、分析

GET /v1/monitors/{id}/analytics(リファレンス)は、モニターのレポートのすべての数字を1つの回答集合から返します。1つの期間、1つのフィルターセット、そして比較のための直前の同じ長さの期間です。自社レポートのすべてのパネルをこのエンドポイントから作り、数字の前に quality を読んでください。レポートの読み取りは無料です。

curl "https://api.querying.ai/v1/monitors/$MONITOR_ID/analytics?since=2026-10-16T00:00:00Z&until=2026-10-18T00:00:00Z&engine=CHATGPT" \
  -H "Authorization: Bearer $QUERYING_API_KEY"

クエリパラメーター

パラメーター	説明
`days`	`7`、`30`(既定)、`90`。期間は現在時点で終わります。`since` と `until` とは併用できません。
`since`、`until`	固定の期間。両方を、`2026-10-16T00:00:00Z` のようなタイムゾーン付きの ISO 8601 時刻で送ります。期間は正で最大90日、`until` は未来にできません。`2026-10-16` のような日付のみの値は拒否されます。
`engine`	このエンジンの回答だけ: モニターのエンジンid、または `GOOGLE_AIO` などのそのエイリアス。
`prompt`	このプロンプトへの回答だけ。完全一致のテキストで1〜2,000文字。回答はプロンプトのテキストで保存されるため、モニターから外したプロンプトも引き続き照会できます。

期間は半開区間でUTC基準です。since は含み、until は含みません。直前の期間はまったく同じ長さで since で終わり、同じフィルターを使うため、すべての比較は同条件です。各パラメーターは1回だけ送ってください。

例

たとえば、ChatGPT に2つのプロンプトを1日1回 samples: 5 で質問する(1日10回答)ブランドモニターを、2日間 ChatGPT で絞り込むと、次を返します。

レスポンス全体

{
  "success": true,
  "data": {
    "monitor": {
      "id": "d39b8de0-b159-4229-bf58-7064e5369db1",
      "name": "Earbud brand tracking",
      "mode": "BRAND",
      "category": null,
      "promptTopics": {},
      "engines": ["CHATGPT", "GEMINI"],
      "prompts": ["best wireless earbuds for commuting", "are cheap earbuds worth it"],
      "aliases": ["Acme Audio", "Acme"],
      "domains": ["acme-audio.example"],
      "country": "US",
      "intervalHours": 24,
      "enabled": true,
      "alertBelowPct": 40,
      "competitors": [
        { "name": "Northwind Audio", "aliases": ["Northwind Audio"], "source": "user" },
        { "name": "Contoso Sound", "aliases": ["Contoso Sound", "Contoso"], "source": "user" }
      ],
      "competitorsReadAt": "2026-10-17T03:10:22.004Z",
      "location": null,
      "grid": null,
      "engineSettings": { "CHATGPT": { "samples": 5 } },
      "webhookUrl": null,
      "analysis": false,
      "nextRunAt": "2026-10-19T09:00:02.118Z",
      "lastRunAt": "2026-10-18T09:00:01.730Z",
      "shareAccess": "PRIVATE",
      "shareSlug": null,
      "createdAt": "2026-10-09T08:59:57.410Z",
      "updatedAt": "2026-10-12T14:21:09.882Z"
    },
    "window": {
      "since": "2026-10-16T00:00:00.000Z",
      "until": "2026-10-18T00:00:00.000Z",
      "previousSince": "2026-10-14T00:00:00.000Z",
      "previousUntil": "2026-10-16T00:00:00.000Z",
      "timezone": "UTC",
      "bounds": "[since, until)"
    },
    "filters": { "engine": "CHATGPT", "prompt": null },
    "stats": { "runs": 20, "mentioned": 9, "cited": 3, "competitorOnly": 7, "mentionRate": 45, "citationRate": 15, "competitorOnlyRate": 35 },
    "previous": { "runs": 20, "mentioned": 12, "cited": 4, "competitorOnly": 5, "mentionRate": 60, "citationRate": 20, "competitorOnlyRate": 25 },
    "changes": { "mentionRatePp": -15, "citationRatePp": -5 },
    "engineRates": [
      { "engine": "CHATGPT", "runs": 20, "mentioned": 9, "cited": 3, "competitorOnly": 7, "mentionRate": 45, "citationRate": 15, "competitorOnlyRate": 35 }
    ],
    "series": [
      {
        "day": "2026-10-16",
        "engine": "CHATGPT",
        "partial": false,
        "runs": 10,
        "mentioned": 5,
        "cited": 2,
        "competitorOnly": 3,
        "mentionRate": 50,
        "citationRate": 20,
        "competitorOnlyRate": 30
      },
      {
        "day": "2026-10-17",
        "engine": "CHATGPT",
        "partial": false,
        "runs": 10,
        "mentioned": 4,
        "cited": 1,
        "competitorOnly": 4,
        "mentionRate": 40,
        "citationRate": 10,
        "competitorOnlyRate": 40
      }
    ],
    "brands": [
      {
        "name": "Northwind Audio",
        "mentions": 10,
        "sampleSize": 20,
        "mentionRate": 50,
        "shareOfVoice": 43.47826086956522,
        "previousMentionRate": 40,
        "previousShareOfVoice": 33.33333333333333,
        "configured": true
      },
      {
        "name": "__you__",
        "mentions": 9,
        "sampleSize": 20,
        "mentionRate": 45,
        "shareOfVoice": 39.130434782608695,
        "previousMentionRate": 60,
        "previousShareOfVoice": 50,
        "configured": true
      },
      {
        "name": "Contoso Sound",
        "mentions": 4,
        "sampleSize": 20,
        "mentionRate": 20,
        "shareOfVoice": 17.391304347826086,
        "previousMentionRate": 20,
        "previousShareOfVoice": 16.666666666666664,
        "configured": true
      }
    ],
    "voiceSeries": [
      { "day": "2026-10-16", "name": "__you__", "mentions": 5, "runs": 10, "mentionRate": 50, "shareOfVoice": 41.66666666666667 },
      { "day": "2026-10-16", "name": "Northwind Audio", "mentions": 5, "runs": 10, "mentionRate": 50, "shareOfVoice": 41.66666666666667 },
      { "day": "2026-10-16", "name": "Contoso Sound", "mentions": 2, "runs": 10, "mentionRate": 20, "shareOfVoice": 16.666666666666664 },
      { "day": "2026-10-17", "name": "__you__", "mentions": 4, "runs": 10, "mentionRate": 40, "shareOfVoice": 36.36363636363637 },
      { "day": "2026-10-17", "name": "Northwind Audio", "mentions": 5, "runs": 10, "mentionRate": 50, "shareOfVoice": 45.45454545454545 },
      { "day": "2026-10-17", "name": "Contoso Sound", "mentions": 2, "runs": 10, "mentionRate": 20, "shareOfVoice": 18.181818181818183 }
    ],
    "prompts": [
      {
        "prompt": "are cheap earbuds worth it",
        "runs": 10,
        "mentioned": 3,
        "cited": 0,
        "competitorOnly": 4,
        "mentionRate": 30,
        "citationRate": 0,
        "competitorOnlyRate": 40,
        "previous": { "runs": 10, "mentioned": 5, "cited": 1, "competitorOnly": 3, "mentionRate": 50, "citationRate": 10, "competitorOnlyRate": 30 },
        "engines": [
          {
            "prompt": "are cheap earbuds worth it",
            "engine": "CHATGPT",
            "runs": 10,
            "mentioned": 3,
            "cited": 0,
            "competitorOnly": 4,
            "mentionRate": 30,
            "citationRate": 0,
            "competitorOnlyRate": 40,
            "previous": { "runs": 10, "mentioned": 5, "cited": 1, "competitorOnly": 3, "mentionRate": 50, "citationRate": 10, "competitorOnlyRate": 30 },
            "mentionRateChangePp": -20,
            "topCompetitor": "Northwind Audio",
            "topCompetitorRate": 60,
            "evidenceTaskId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a63",
            "mentionTaskId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a63",
            "latestTaskId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a63"
          }
        ]
      },
      {
        "prompt": "best wireless earbuds for commuting",
        "runs": 10,
        "mentioned": 6,
        "cited": 3,
        "competitorOnly": 3,
        "mentionRate": 60,
        "citationRate": 30,
        "competitorOnlyRate": 30,
        "previous": { "runs": 10, "mentioned": 7, "cited": 3, "competitorOnly": 2, "mentionRate": 70, "citationRate": 30, "competitorOnlyRate": 20 },
        "engines": [
          {
            "prompt": "best wireless earbuds for commuting",
            "engine": "CHATGPT",
            "runs": 10,
            "mentioned": 6,
            "cited": 3,
            "competitorOnly": 3,
            "mentionRate": 60,
            "citationRate": 30,
            "competitorOnlyRate": 30,
            "previous": { "runs": 10, "mentioned": 7, "cited": 3, "competitorOnly": 2, "mentionRate": 70, "citationRate": 30, "competitorOnlyRate": 20 },
            "mentionRateChangePp": -10,
            "topCompetitor": "Northwind Audio",
            "topCompetitorRate": 40,
            "evidenceTaskId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a61",
            "mentionTaskId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a61",
            "latestTaskId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a61"
          }
        ]
      }
    ],
    "opportunities": [
      {
        "prompt": "are cheap earbuds worth it",
        "engine": "CHATGPT",
        "runs": 10,
        "mentioned": 3,
        "cited": 0,
        "competitorOnly": 4,
        "mentionRate": 30,
        "citationRate": 0,
        "competitorOnlyRate": 40,
        "previous": { "runs": 10, "mentioned": 5, "cited": 1, "competitorOnly": 3, "mentionRate": 50, "citationRate": 10, "competitorOnlyRate": 30 },
        "mentionRateChangePp": -20,
        "topCompetitor": "Northwind Audio",
        "topCompetitorRate": 60,
        "evidenceTaskId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a63",
        "mentionTaskId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a63",
        "latestTaskId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a63"
      },
      {
        "prompt": "best wireless earbuds for commuting",
        "engine": "CHATGPT",
        "runs": 10,
        "mentioned": 6,
        "cited": 3,
        "competitorOnly": 3,
        "mentionRate": 60,
        "citationRate": 30,
        "competitorOnlyRate": 30,
        "previous": { "runs": 10, "mentioned": 7, "cited": 3, "competitorOnly": 2, "mentionRate": 70, "citationRate": 30, "competitorOnlyRate": 20 },
        "mentionRateChangePp": -10,
        "topCompetitor": "Northwind Audio",
        "topCompetitorRate": 40,
        "evidenceTaskId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a61",
        "mentionTaskId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a61",
        "latestTaskId": "6f1c2a9e-3b4d-4e5f-8a7b-1c2d3e4f5a61"
      }
    ],
    "quality": {
      "comparable": true,
      "comparisonReason": null,
      "scoringVersions": ["3f9a6c1e8b2d4f7a9c0e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a3c5e7b9d1f3a"],
      "noAnswerObservations": 0,
      "unknownObservations": 0,
      "noAnswerIncluded": true,
      "historicalFailures": null,
      "sampleSize": 20,
      "previousSampleSize": 20,
      "configuredCells": 2,
      "observedCells": 2,
      "missingCells": 0,
      "lowSample": true,
      "partialDays": [],
      "denominator": "scored_answers",
      "shareOfVoiceDenominator": "tracked_brand_mentions",
      "trackedBrandMentions": 23,
      "answerTextLimit": 8000,
      "scoring": "collection_time_definitions",
      "failedTasksIncluded": false
    },
    "pauses": [],
    "health": { "completed": 12, "failed": 0, "pending": 0, "topError": null },
    "healthScope": "recent_visible_tasks"
  }
}

読み方: ブランドは ChatGPT の20回答のうち9件(45%)で挙げられ、直前の2日間から15ポイント下がっています。Northwind Audio はより多くの回答で挙げられ、「are cheap earbuds worth it」が最も弱いプロンプトで、競合を挙げてブランドを挙げなかった回答が4件あります。quality.lowSample が true なので、この変化は傾向ではなく確認すべき兆候として扱ってください。

レスポンスのセクション

フィールド	内容
`monitor`	保存されたモニターの定義。
`window`	`since`、`until`、`previousSince`、`previousUntil`、`timezone`(`UTC`)、`bounds`(`[since, until)`)。`previousUntil` は常に `since` と等しくなります。
`filters`	適用されたフィルターの解決値: 正規のエンジンid、完全一致のプロンプト、または `null`。
`stats`、`previous`	今回の期間と直前の期間の件数と比率。比率オブジェクトを参照してください。
`changes`	`mentionRatePp` と `citationRatePp`: パーセントポイントの変化量。比較が保留される場合は `null`。
`engineRates`	エンジンごとの比率オブジェクト。
`series`	UTCの日とエンジンごとの比率オブジェクト。期間が一部しか含まない日は `partial: true`。
`brands`	自社ブランド(`__you__`)と期間内に挙げられたすべての競合、言及の多い順。ブランドとシェア・オブ・ボイスを参照してください。
`voiceSeries`	UTCの日とブランドごとの `mentions`、`runs`(その日の回答数)、`mentionRate`、`shareOfVoice`。
`prompts`	プロンプトごと、言及率の低い順: 比率オブジェクト、`previous`、エンジンごとに1セルの `engines`。
`opportunities`	競合は挙げられたのに自社ブランドは挙げられなかったセル(`competitorOnly` が0より大きい)、該当回答の多い順。取り組むべきリストです。
`quality`	サンプルの構成と、数字が語れないこと。品質を参照してください。
`pauses`	期間と重なる一時停止、古い順: `pausedAt` と `resumedAt`(一時停止中は `null`)。
`health`、`healthScope`	直近のタスク状態。レポートとは別のスコープです。ヘルスを参照してください。

比率オブジェクト

stats、previous、engineRates と series の各エントリ、各プロンプト、各セルは同じフィールドを持ちます。

フィールド	意味
`runs`	採点された回答。以下のすべての比率の分母です。
`mentioned`	自社ブランドを挙げた回答。
`cited`	自社ドメインのいずれかを引用した回答。
`competitorOnly`	競合を1社以上挙げ、自社ブランドを挙げなかった回答。
`mentionRate`、`citationRate`、`competitorOnlyRate`	`100 × 件数 / runs`。`runs` が0なら `null`。

セル

セルは1つのエンジン上の1つのプロンプトです。比率オブジェクトと previous に加えて、次を持ちます。

フィールド	意味
`mentionRateChangePp`	セルのポイント変化量。比較が保留される場合は `null`。
`topCompetitor`	セルの回答で最も多く挙げられた競合、または `null`。
`topCompetitorRate`	セル内のその競合の言及率。セルの回答の一部が採点コンテキストの保存前のものなら `null`。
`evidenceTaskId`	競合を挙げて自社ブランドを挙げなかった最新の回答。
`mentionTaskId`	自社ブランドを挙げた最新の回答。
`latestTaskId`	最新の回答。

該当する回答がなければ各idは null です。 GET /v1/monitors/{id}/answers/{taskId}で開きます。

ブランドとシェア・オブ・ボイス

brands の各エントリは name、mentions、sampleSize、mentionRate、shareOfVoice、previousMentionRate、 previousShareOfVoice、configured(期間内に挙げられたがもうモニターにないブランドは false)を持ちます。

数字の意味

GET /v1/monitors/capabilities はこれらの定義を metrics として返すため、クライアントは数字の横に表示できます。

mentionRate は、期間、各エンジン、各日、各セルについて 100 × mentioned / 採点された回答 です。エンジン間の平均ではなく回答数で重み付けするため、回答の多いエンジンが少ないエンジンに埋もれません。
citationRate は、自社ドメインのいずれかを引用した回答について同じ形で数えます。ドメインがなければ引用追跡がオフなので、常に0です。
ブランドの比率は自身の sampleSize で割ります。 自社ブランドは採点されたすべての回答です。競合はモニターに登録されていた間に採点された回答だけなので、今日追加した競合は今日から測定されます。期間内の一部の回答が採点コンテキストの保存前に採点されている場合、何と照合されたか分からないため、競合の mentionRate は null です。
shareOfVoice は期間内の 100 × そのブランドの言及 / 追跡中の全ブランドの言及 なので、1つの期間のシェアを合計すると100になります(分母は quality.trackedBrandMentions)。これらのプロンプトで収集した回答の中でブランドを比較する値であり、市場シェアでも可視性のランキングでもありません。
competitorOnly と opportunities は、自社ブランドがなく競合を挙げた回答を数えます。手を打てるギャップです。
null は0ではありません。 割る回答がなければ比率は null です。0は回答があり1つも一致しなかったことを意味します。
テキストのない回答は「言及なし」として数えます。 回答を返さずに完了したタスクは分母に残り、 quality.noAnswerObservations がその数を示します。失敗したタスクはすべての比率から除外され、health にだけ現れます。壊れたエンジンは不在として現れるのではなく、サンプルを減らします。
採点済みの回答の position は、自社ブランドが最初に一致した箇所の文字オフセットです。順位ではなく目立ち具合の代理指標です。ブランドがなければ null です。

比較が保留される場合

2つの期間を比較できない場合、changes、各セルの mentionRateChangePp、各ブランドの previousMentionRate と previousShareOfVoice は null になり、quality.comparable は false です。理由は quality.comparisonReason が示します。

`comparisonReason`	意味
`insufficient_periods`	2つの期間の一方に回答がありません。
`legacy_scoring_unknown`	一部の回答が、採点に使った定義の保存前に採点されています。
`scoring_definitions_changed`	2つの期間の回答の間で、エイリアス、ドメイン、競合、国のいずれかが変わりました。

すべての回答は採点時の定義を保持し、quality.scoringVersions は両期間の異なる定義を列挙します(定義のない回答は legacy)。エイリアスや競合を変えても過去の回答が書き換わることはありません。唯一の例外は週次の競合読み取りで、見つけた競合が変わると、モニターに保存された回答を新しい一覧で採点し直します。

品質

フィールド	意味
`comparable`、`comparisonReason`	変化量を表示するかどうかと、表示しない理由。
`scoringVersions`	両期間の異なる採点定義。
`scoring`	常に `collection_time_definitions`: 回答は届いた時点で有効だった定義で採点されます。
`sampleSize`、`previousSampleSize`	各期間の採点された回答。
`lowSample`	期間内の採点された回答が30未満なら `true`。
`configuredCells`、`observedCells`、`missingCells`	フィルターが対象とするプロンプト × エンジンのセル、1件以上の回答があるセル、その差。
`partialDays`	期間が途中で切る、またはまだ終わっていないUTCの日。部分日の件数が少ないのは計算上の結果であり、減少ではありません。
`noAnswerObservations`	テキストのない完了した回答。「言及なし」として数えます。
`unknownObservations`	採点コンテキストの保存前に採点された回答。
`noAnswerIncluded`、`failedTasksIncluded`、`historicalFailures`	常に `true`、`false`、`null`: テキストのない回答は分母に含まれ、失敗したタスクは含まれず、失敗が履歴から再構成されることはありません。
`denominator`、`shareOfVoiceDenominator`	`scored_answers` と `tracked_brand_mentions`。
`trackedBrandMentions`	シェア・オブ・ボイスの分母。
`answerTextLimit`	`8000`: 保存される回答テキストは8,000文字で切り詰められます。

ヘルス

health は、処理中または直近24時間に終了したモニターのタスクについて、completed、failed、pending、topError (失敗したタスクで最も多いエラーコード)を持ちます。healthScope は常に recent_visible_tasks です。期間とは独立した実行の診断情報で、比率の分母には決して含まれません。

実行中にポーリングする

すべての呼び出しは、その期間とフィルターでの完全なレポートを返します。実行中は、health.pending がまだ処理中のタスク数を数えます。0になったらレポートを読み直してください。

カテゴリレポート

カテゴリモニターは同じエンドポイントから異なるボディを返します。window、filters、 quality、pauses、health は同じです。

stats と previous は runs、named(追跡ブランドを1つ以上挙げた回答)、namedRate を持ちます。 changes.namedRatePp はポイント差です。
category が順位を持ちます。

フィールド	内容
`category.name`	モニターの `category`。
`category.brands`	すべての追跡ブランドと回答が挙げたすべてのブランド、言及の多い順: `name`、`rank`、`mentions`、`sampleSize`、`mentionRate`、`shareOfVoice`、`previousMentionRate`、`previousShareOfVoice`、`changePp`、`configured`。
`category.topics`	サブ分野ごとに1行(`topic: null` はカテゴリ全体): `prompts`、`runs`、`named`、`namedRate`、最も多く挙げられた3ブランドの `leaders`。
`category.engines`	期間内に回答があるエンジンごとに1行: `runs`、`named`、`namedRate`、`leaders`。
`category.series`	UTCの日ごとの上位5つの追跡ブランド: `mentions`、`sampleSize`、`runs`、`mentionRate`、`partial`。
`category.prompts`	プロンプトごとに1行: `topic`、`retired`(もうモニターにないプロンプトは `true`)、`runs`、`named`、`namedRate`、`leaders`、`engines`。各エンジンは `runs`、`named`、ブランドを挙げた最新の回答の `evidenceTaskId` を持ちます。

たとえば、category.brands の1エントリ:

{
  "name": "Northwind Sun",
  "mentions": 18,
  "sampleSize": 40,
  "mentionRate": 45,
  "shareOfVoice": 30,
  "previousMentionRate": 40,
  "previousShareOfVoice": 25,
  "changePp": 5,
  "configured": true,
  "rank": 1
}

rank は、ブランドを挙げた回答の数で順序付けします。どの回答にも挙げられなかったブランドは rank: null です。
mentionRate はブランド自身の sampleSize(一覧にあった間に採点された回答)で割ります。
shareOfVoice は期間内の 100 × そのブランドの言及 / 全ブランドの言及 なので、シェアの合計は100になります。

エラーと上限

期間は最大90日です。
不正なパラメーターは問題を示すメッセージ付きで 400 VALIDATION_ERROR を返します: since または until と days の併用、since と until の一方だけ、タイムゾーンのない時刻、90日を超える期間、未来の until、モニターできないエンジン、2,000文字を超えるプロンプト、繰り返されたパラメーター。
集計するには大きすぎるレポートは「This report is too large」付きで 400 VALIDATION_ERROR を返します。期間、エンジン、プロンプトを絞ってください。

すべてのモニターエンドポイントに共通するコードはモニターを参照してください。

はじめに

基本概念

回答エンジン

検索とウェブデータ

リクエストオプション

リサーチ

GEOモニタリング

アカウントとデータ

モニターレポート: 言及率、シェア・オブ・ボイス、分析

クエリパラメーター

例

レスポンスのセクション

比率オブジェクト

セル

ブランドとシェア・オブ・ボイス

数字の意味

比較が保留される場合

品質

ヘルス

実行中にポーリングする

カテゴリレポート

エラーと上限

次のステップ

ソースと回答

イベントとアラート

​クエリパラメーター

​例

​レスポンスのセクション

​比率オブジェクト

​セル

​ブランドとシェア・オブ・ボイス

​数字の意味

​比較が保留される場合

​品質

​ヘルス

​実行中にポーリングする

​カテゴリレポート

​エラーと上限

​次のステップ

ソースと回答

イベントとアラート

クエリパラメーター

例

レスポンスのセクション

比率オブジェクト

セル

ブランドとシェア・オブ・ボイス

数字の意味

比較が保留される場合

品質

ヘルス

実行中にポーリングする

カテゴリレポート

エラーと上限

次のステップ