> ## 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/zh/monitors)开始。

本页中的所有密钥、id、品牌和提示词均为示例，都不是真实的凭据或真实的监测器。

## 什么是监测器

监测器是**针对一个市场的具名提示词集**：一组提示词、要发送到的引擎、代表“你的品牌”的别名、可选的你的域名和
几个竞争对手、一个国家以及一个运行间隔。每次计划运行会提交 提示词 × 引擎 个普通异步任务，每个完成的回答只评分一次并保存。

评分范围刻意收窄，数据无法回答超出其存储内容的问题：

* 它记录品牌别名是否出现在回答文本中及其字符偏移量；回答是否引用了你登记的某个域名；以及你配置的哪些竞争对手出现在同一回答中。
* 它**不会**生成情感评分或市场份额估算。排名指的是在回答所提到的品牌中的位置，如下文品类监测器的品牌排名。

### 竞争对手会自动找出

你不需要列出竞争对手。监测器的首次运行完成后，我们会用语言模型读取它最近的回答，保留与你销售同类产品、并且在至少两个回答中
被提到的品牌，最多 15 个。这项读取每 30 天重复一次，因此新的对手会加入，不再被提到的会移除。

* 找出的竞争对手带有 `source: "auto"`，你自己添加的带有 `source: "user"`，读取永远不会修改或删除后者。
* 找出的名单变化时，监测器已保存的回答会按新名单重新计数，因此报告中的每个品牌都在相同的回答上测量。监测器的
  `competitorsReadAt` 记录最近一次读取的时间。
* 拉丁字母的名称按整词匹配，所以 “replicates” 不算作品牌 Replicate 的提及。

### 有意识地划分监测器

不同的监测器代表不同的主题或市场，也是彼此独立的报告：各自有自己的窗口、评分定义和计划。两个习惯很有帮助：

* 每个主题和市场一个监测器，使报告的样本组保持可比。把“最好的 CRM”和“CRM 如何定价”混进一个提示词集，
  会把两种不同意图平均成一个数字。
* 提示词要用购买者的口吻，绝不要包含你自己的品牌。包含品牌的提示词总会被判为提及，永远报告 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`（提到至少一个被跟踪品牌的回答数）和
`namedRate`，`changes.namedRatePp` 是百分点变化，`category` 对象包含排名：

| 字段 | 内容 |
| - | - |
| `category.brands` | 回答提到的每个被跟踪品牌，提到它的回答越多越靠前：`rank`、`mentions`、`sampleSize`、`mentionRate`、`shareOfVoice`，以及与上一个区间相比的变化。 |
| `category.topics` | 每个细分领域一行（`topic: null` 表示整个品类），含 `runs`、`namedRate` 和被提到最多的三个品牌。 |
| `category.engines` | 每个引擎一行，含它提到最多的三个品牌。 |
| `category.series` | 按 UTC 日，排名前五品牌的比率。 |
| `category.prompts` | 每个提示词一行，含领先品牌和按引擎的单元格；每个单元格带有 `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](/zh/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`。控制台的**运行研究**按钮做同样的事并填好表单；在你创建监测器之前，什么都不会保存。

## 成本与计划

一次运行会为每个提示词、每个引擎排入一个任务，按各引擎公布的额度价格计费。计划会一直重复，直到你暂停或删除监测器，
因此你在创建时选择的是持续成本：

```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 额度），每次运行 24 个任务、36 额度；按每天一次计算，
每月约 1,080 额度。请从 capabilities 端点读取实时价格，而不要硬编码。

在依赖计划之前，有两点值得了解：

* 一次运行**不是**瞬时爆发。任务按套餐并发和队列允许的速度进入，因此超过免费套餐上限的运行会在几分钟内陆续到达，
  而不会被丢弃。在报告中查看 `health.pending` 可了解正在进行的运行。
* 下一个窗口是一个时间点，而非保证。`nextRunAt` 是运行到期的时间；暂停一周的监测器在重新启用后从当时起过一个间隔
  再恢复，而不会补跑错过的运行。

自动查找竞争对手每个监测器每月另加 100 积分，按运行间隔分摊到每次运行：每天运行的监测器每次约 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` | **报告协议。** 一个样本组、一套过滤条件、所有板块。 |
| `GET /v1/monitors/{id}/sources` | 同一窗口内被引用的域名或页面，分页返回。 |
| `GET /v1/monitors/{id}/citations` | 热门域名和页面的每日引用数，即控制台引用图表所用的数据。 |
| `GET /v1/monitors/{id}/results` | 评分行本身，JSON 或 CSV，支持过滤和游标。 |
| `GET /v1/monitors/{id}/answers/{taskId}` | 某一行背后保存的回答。 |
| `GET /v1/monitors/{id}/prompt` | 单个提示词的下钻：时间序列、来源和最近的行。 |
| `GET /v1/monitors/{id}/alerts` · `POST .../alerts/test` | 告警阈值、锁存状态和投递历史；排入一封测试邮件。 |
| `POST /v1/monitors/suggest` | 根据品牌信息生成的候选提示词。不保存任何内容，也不消耗任务额度。 |
| `POST /v1/monitors/research` | 为监测器研究提示词：与 [Prompt Research](/zh/research/prompt-research) 相同的请求、价格和结果，以你的账户提交。 |

它们都使用与 API 其余部分相同的 Bearer 密钥（参见[认证](/zh/authentication)）。其他账户拥有的监测器返回 `404`，而不是 `403`。

## 创建监测器

```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` 在品牌监测器上为必填；品类监测器用 `category` 代替 `aliases`。每个列表都接受数组或一个以换行分隔的字符串；
条目会去除首尾空白，丢弃空行并去重。`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` 让下一次运行立即到期，回答任务约一分钟内出现。它与计划运行一样计费；在该窗口仍处于
到期状态时重试调用不会重复计费。

`GET /v1/monitors/{id}/analytics` 是报告中每一部分都应依据的协议。它的窗口是**半开区间，以 UTC 计**：`since` 包含，
`until` 不包含，可以用以下两种方式之一选择：

| 参数 | 规则 |
| - | - |
| `days` | `7`、`30`（默认）或 `90` 之一，截止到现在。不能与 `since`/`until` 同时使用。 |
| `since` 和 `until` | 必须同时提供，且为**带时区**的完整 ISO 时刻（例如 `2026-09-15T00:00:00Z`）。跨度必须为正、最多 90 天，且不能在未来。这里会拒绝单独的 `YYYY-MM-DD`，因为它无法定义可移植的窗口。 |

两个可选过滤条件会同时作用于**所有**板块：`engine`（规范 id 或公开别名）和 `prompt`（精确文本，最多 2,000 个字符）。
行以提示词文本为键，因此你之后从监测器中移除的提示词仍可查询。

所有板块共享这一个样本组，而上一个区间的时长和过滤条件完全相同，因此比较是同口径的：

| 字段 | 内容 |
| - | - |
| `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`，而不是窗口总数。** 对你的品牌来说，就是所有已评分回答；对竞争对手来说，
  只是它在监测器上期间评分的回答。今天添加一个竞争对手，它的首份报告只覆盖测量过它的回答，之前的历史不会计入它的不利。
  没有合格回答的品牌报告 `mentionRate: null` 而不是 0%，因为 0% 会被读成真的消失了。
* `brands` 中的 **`shareOfVoice`** 是窗口内 `100 × 该品牌提及数 / 所有被追踪品牌的提及总数`，因此同一窗口的份额之和为 100。
  它比较的是**你为这些提示词收集到的回答**中的品牌，不是市场份额，也不是可见度排名。旧版详情端点的 `shareOfVoice` 是较早的
  回答渗透率视角，每个品牌都以收集到的回答数为基数，总和可能超过 100。不要把两者放在同一张图表里。
* **`competitorOnly`**（以及 `opportunities` 列表）统计提到了已配置竞争对手而没有你的品牌的回答。这是你可以采取行动的差距。
* **比率可以为空，而不是零。** 窗口内没有回答时为 `null`；比率为零表示有回答但都不匹配。
* **没有回答的已完成观测计为未提及。** 它保留在分母中，`quality.noAnswerObservations` 给出数量。**失败**的任务不计入任何比率，
  只出现在 `health` 中。故障引擎会缩小样本，而不是悄悄变成缺席，`quality` 也绝不会把它重构为缺席
  （`historicalFailures` 始终为 `null`）。
* **会误导的变化会被隐藏。** 当某一周期没有回答（`insufficient_periods`）、行是在评分上下文存在之前评分的
  （`legacy_scoring_unknown`），或两个周期之间评分定义发生变化（`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` 回答“哪些页面在赢得这些提示词”，使用与报告相同的窗口和过滤条件，统计的是**不同回答数**
而非原始引用数，因此一个回答中被引用三次的页面只计一次。

| 参数 | 规则 |
| - | - |
| `groupBy` | `domain`（默认，去掉 `www.` 的主机名）或 `page`（带标签的完整 URL）。 |
| `limit` | 1–100，默认 20。 |
| `cursor` | 上一次响应的 `nextCursor`，原样传回。`null` 表示列表结束。 |
| `days` / `since`+`until` / `engine` / `prompt` | 与报告完全相同。 |

每一行包含 `citations` 和 `prompts`（均为不同回答数）、表示你登记域名的 `own`，以及可用 answers 端点打开的
`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 行。 |

这里的一次引用是指一个页面出现在一条回答中，因此同一页面在同一回答中出现两次只算一次。
`/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`（带 BOM 的 UTF-8，以便 Excel 正确打开），分页状态移到响应头中，
因为 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}` 返回某一行保存的证据：

* `answerText`：引擎给出的原样回答，尽可能为 markdown，**最多 8,000 个字符**，更长时截断并加上省略号。
* `sources`：按引擎顺序的引用，每条带标签以及在引用列表中从 1 开始的位置。
* `aliases` 和 `competitors`：该行所匹配的对象，让你可以核查提及而不是盲目信任。
* `scoringContext`：所使用的确切定义，包括 `version` 哈希、评分时间、`answerPresent`，以及上述文本被截断时的 `evidenceTruncated`。

在存储评分上下文之前评分的行返回 `scoringKnown: false`、监测器当前的别名以及值为 `null` 的 `evidenceTruncated`。
引擎未返回回答文本时 `answerText` 为 `null`。

## 本模块的错误

信封与其他地方相同（参见[错误](/zh/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 次，每小时 30 次）或测试告警邮件（每个监测器每五分钟 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/zh/pricing)和[引擎参考](/zh/engines/overview)。