Skip to main content
监测器按计划重复运行一组保存的提示词,并针对你的品牌及其竞争对手为得到的 AI 回答评分。本页是 API 协议: 如何配置监测器、每个数字的含义、如何读取其背后的来源,以及如何导出底层回答。若想在控制台查看同样的数据, 请从产品指南开始。 本页中的所有密钥、id、品牌和提示词均为示例,都不是真实的凭据或真实的监测器。

什么是监测器

监测器是针对一个市场的具名提示词集:一组提示词、要发送到的引擎、代表“你的品牌”的别名、可选的你的域名和 几个竞争对手、一个国家以及一个运行间隔。每次计划运行会提交 提示词 × 引擎 个普通异步任务,每个完成的回答只评分一次并保存。 评分范围刻意收窄,数据无法回答超出其存储内容的问题:
  • 它记录品牌别名是否出现在回答文本中及其字符偏移量;回答是否引用了你登记的某个域名;以及你配置的哪些竞争对手出现在同一回答中。
  • 它不会生成情感评分或市场份额估算。排名指的是在回答所提到的品牌中的位置,如下文品类监测器的品牌排名。

竞争对手会自动找出

你不需要列出竞争对手。监测器的首次运行完成后,我们会用语言模型读取它最近的回答,保留与你销售同类产品、并且在至少两个回答中 被提到的品牌,最多 15 个。这项读取每 30 天重复一次,因此新的对手会加入,不再被提到的会移除。
  • 找出的竞争对手带有 source: "auto",你自己添加的带有 source: "user",读取永远不会修改或删除后者。
  • 找出的名单变化时,监测器已保存的回答会按新名单重新计数,因此报告中的每个品牌都在相同的回答上测量。监测器的 competitorsReadAt 记录最近一次读取的时间。
  • 拉丁字母的名称按整词匹配,所以 “replicates” 不算作品牌 Replicate 的提及。

有意识地划分监测器

不同的监测器代表不同的主题或市场,也是彼此独立的报告:各自有自己的窗口、评分定义和计划。两个习惯很有帮助:
  • 每个主题和市场一个监测器,使报告的样本组保持可比。把“最好的 CRM”和“CRM 如何定价”混进一个提示词集, 会把两种不同意图平均成一个数字。
  • 提示词要用购买者的口吻,绝不要包含你自己的品牌。包含品牌的提示词总会被判为提及,永远报告 100%,什么也测量不到。 竞争对手名称没问题,往往还是你能写出的最有用的提示词。

品类监测器:为市场中的品牌排名

品牌监测器跟踪一个品牌。品类监测器跟踪一个市场:你为品类命名,把问题按细分领域分组,报告会为引擎在回答中提到的品牌排名。 创建监测器时设置 "mode": "CATEGORY"。mode 默认为 BRAND,并且在监测器的整个生命周期内保持不变,因为它决定了每一条已存储行的含义。
计划、成本、窗口、筛选、quality、来源、引用、结果和回答的工作方式与品牌监测器相同。品类监测器没有提醒,因此 POST /v1/monitors/{id}/alerts/test 返回 400。

报告排名的内容

GET /v1/monitors/{id}/analytics 返回品类视图。stats 和 previous 包含 runs、named(提到至少一个被跟踪品牌的回答数)和 namedRate,changes.namedRatePp 是百分点变化,category 对象包含排名:
  • 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 的请求体,花费同样的 12 个额度,返回同样的结果, 并以你的账户提交任务。用 GET /v1/async/task/{id} 读取排队中的任务,任务 id 在响应的 data.task.id 中。
把 monitorSet.prompts 用作 prompts,把每个提示词的 topic 用作 promptTopics 中的细分领域,把 brands[].brand 用作 competitors。控制台的运行研究按钮做同样的事并填好表单;在你创建监测器之前,什么都不会保存。

成本与计划

一次运行会为每个提示词、每个引擎排入一个任务,按各引擎公布的额度价格计费。计划会一直重复,直到你暂停或删除监测器, 因此你在创建时选择的是持续成本:
例如,12 个提示词分别发往 ChatGPT(2 额度)和 Gemini(1 额度),每次运行 24 个任务、36 额度;按每天一次计算, 每月约 1,080 额度。请从 capabilities 端点读取实时价格,而不要硬编码。 在依赖计划之前,有两点值得了解:
  • 一次运行不是瞬时爆发。任务按套餐并发和队列允许的速度进入,因此超过免费套餐上限的运行会在几分钟内陆续到达, 而不会被丢弃。在报告中查看 health.pending 可了解正在进行的运行。
  • 下一个窗口是一个时间点,而非保证。nextRunAt 是运行到期的时间;暂停一周的监测器在重新启用后从当时起过一个间隔 再恢复,而不会补跑错过的运行。
自动查找竞争对手每个监测器每月另加 100 积分,按运行间隔分摊到每次运行:每天运行的监测器每次约 3 积分,每周运行的约 23 积分。 它在一次运行的任务全部进入后才收取,因此因余额不足而停下的运行不会为此付费。

端点

它们都使用与 API 其余部分相同的 Bearer 密钥(参见认证)。其他账户拥有的监测器返回 404,而不是 403。

创建监测器

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 不包含,可以用以下两种方式之一选择: 两个可选过滤条件会同时作用于所有板块:engine(规范 id 或公开别名)和 prompt(精确文本,最多 2,000 个字符)。 行以提示词文本为键,因此你之后从监测器中移除的提示词仍可查询。 所有板块共享这一个样本组,而上一个区间的时长和过滤条件完全相同,因此比较是同口径的:

数字的含义

在给控制台面板命名之前请先阅读。这些定义是公开协议,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 回答“哪些页面在赢得这些提示词”,使用与报告相同的窗口和过滤条件,统计的是不同回答数 而非原始引用数,因此一个回答中被引用三次的页面只计一次。 每一行包含 citations 和 prompts(均为不同回答数)、表示你登记域名的 own,以及可用 answers 端点打开的 evidenceTaskId。这里没有暗中截断前 N 名:沿着游标即可访问窗口内的每个域名或页面。

引用趋势

GET /v1/monitors/{id}/citations 原样返回控制台引用图表所用的数据:窗口内的每日引用总数, 以及每个热门域名和页面的每日序列。它只读取已存储的结果,因此不消耗积分。 这里的一次引用是指一个页面出现在一条回答中,因此同一页面在同一回答中出现两次只算一次。 /sources 统计的是不同回答的数量,所以数字可能不同。 某个来源的占比等于它的 citations 除以 totals.citations。kind、q 和 offset 只缩小列表; totals、days 和 types 始终覆盖窗口内的全部来源。

导出评分行

GET /v1/monitors/{id}/results 返回行本身,可用于数据仓库加载、每周汇报材料或电子表格。 分页基于微秒精度的 (ranAt, id) 键集,因此共享同一时间戳的行不会被跳过或重复。要让抽取可重复:**发送明确的 since 和 until,保持不变,并沿 nextCursor 直到它为 null。**在翻页之间改变窗口可能导致行被跳过或重复。 请将游标视为不透明值:只返回和回传,绝不自行构造。 使用 format=csv 时,响应为 text/csv(带 BOM 的 UTF-8,以便 Excel 正确打开),分页状态移到响应头中, 因为 CSV 正文里没有别的地方可放: 列为 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。

本模块的错误

信封与其他地方相同(参见错误);监测特有的错误码如下:

让智能体参与其中

以下是智能体或脚本仅使用本页端点即可执行的实用流程。仅为示例,请替换为你自己的密钥、监测器 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 会在调用前说明会消耗额度。

限制

在提高用量之前,请查看价格和引擎参考。