跳转到主要内容
监测器只需创建一次。每次运行都是一组普通的异步任务,按各引擎的价格计费。 本页介绍如何创建、运行和管理监测器。如何解读数字见报告与指标,数字背后的回答见 来源与回答,Webhook 和邮件提醒见事件与提醒。若想在控制台查看同样的数据,请参阅 产品页面。

品牌监测器与品类监测器

监测器有一个 mode,在创建时设置,并在整个生命周期内保持不变,因为它决定了每条已保存回答的含义。 每个回答在到达时评分一次:
  • 提及:你的某个别名出现在回答文本中。position 是首个匹配的字符偏移量,品牌未出现时为 null。
  • 引用:回答引用了你某个 domains 或其子域名上的页面。
  • 竞争对手命中:监测器的哪些竞争对手出现在同一回答中。
这些评分不含情感,也不估算市场份额。品类监测器的排名只是在回答所提到的品牌中的位置,仅此而已。如需每个回答的情感和建议,请开启 analysis。

快速开始

1

创建监测器

监测器创建后,首次运行立即开始。
响应为 201,并返回已保存的监测器。请记下 data.monitor.id。
2

等待回答

任务按套餐并发允许的速度进入,因此一次运行会在几秒到几分钟内陆续到达。 报告中的 health.pending 统计仍在进行中的任务。它变为 0 后再读取报告。
3

读取报告

先读 quality,再读 stats、brands 和 opportunities。每个字段都在 报告与指标中说明。
如需在下一次计划运行之前获取回答,请调用 POST /v1/monitors/{id}/run。

创建监测器

POST /v1/monitors(参考)校验定义,按账户限制检查,保存后启动首次运行。 该调用在首次运行完成前就返回 201。如果首次运行无法开始(例如余额不足),监测器仍会创建,调度器每分钟重试一次该运行。 例如,快速开始中的请求返回:

请求字段

每个列表字段都接受 JSON 数组或一个以换行分隔的字符串。条目会去除首尾空白,空条目被丢弃,重复项被移除。

引擎

监测器可以调度基于提示词的回答引擎: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)不能被调度。价格和各引擎详情见引擎目录。 限制了部分引擎的 API 密钥只能创建、更新或运行使用这些引擎的监测器;其他情况返回 403 KEY_SCOPE_DENIED。

竞争对手

你不需要列出竞争对手。首次运行后,每周会读取一次监测器最近的回答,加入与你销售同类产品、并且在至少两个回答中出现的品牌: 品牌监测器最多 15 个,品类监测器最多 25 个。
  • 找出的竞争对手带有 source: "auto",你列出的带有 source: "user"。读取永远不会修改或删除你列出的。 连续两次读取都没有找到的已找出品牌会被移除。
  • 找出的名单变化时,监测器已保存的回答会按新名单重新评分,因此报告中的每个品牌都在相同的回答上测量。competitorsReadAt 记录最近一次读取的时间。
  • 更新时,competitors 替换你自己的名单并保留找出的品牌。请求中带有 source: "auto" 的条目会被忽略,因此你可以把 GET 返回的内容原样发回。

名称如何匹配

  • 匹配不区分大小写和字符全半角(NFKC)。
  • 拉丁字母的名称只按整词匹配:“replicates” 不算作品牌 Replicate 的提及。紧挨名称的韩文、假名、汉字或泰文字符视为词的边界,因此 “agoda를” 和 “ahamoが” 算作 agoda 和 ahamo 的提及。韩文、日文、中文和泰文名称在文本中任意位置都可匹配。
  • 单个字符的名称永远不会匹配。请为这类品牌设置更长的别名。
  • 两个名称重叠时,先出现的优先,其次是更长的。名为 “Acme Pro” 的竞争对手中的 “Acme” 算作该竞争对手。
  • 匹配前会移除链接目标、裸 URL 和引用标记;链接的可见文字会保留。引用计入 cited,不计为提及。

写出能测量的提示词

  • 每个主题和市场一个监测器。“最好的 CRM”和“CRM 如何定价”是不同的意图,平均到一起会把两者都掩盖。
  • 提示词要用购买者的口吻,绝不要包含你自己的品牌。包含品牌的提示词总会被判为提及,永远报告 100%,什么也测量不到。提示词中出现竞争对手名称没问题。

样本数与各引擎频率

AI 回答在不同会话之间会变化,因此多个回答的占比比单个回答更稳定。engineSettings 按引擎设置每个提示词收集多少个回答,以及该引擎多久运行一次:
  • samples:每次运行中每个提示词和地点收集 1–10 个回答(默认 1)。每个回答都是在独立会话中的单独任务,像其他任务一样评分和计费。
  • intervalHours:监测器 intervalHours 的倍数,最多 168。该引擎每隔 k 次运行参加一次,从首次运行开始计数,首次运行所有引擎都参加。
条目只能指定监测器自己的引擎,且只接受这两个键。更新时,engineSettings 会替换已保存的值;移除某个引擎的更新会一并移除它的条目, 修改监测器 intervalHours 的更新会按新值检查各引擎的间隔。

地点与网格

默认情况下,每个任务都针对整个国家询问。要测量本地回答:
  • location 从一个地点询问每个提示词,以十进制度数表示。
  • 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 中带上地址,抽屉会把它作为内嵌字体的文件提供。页面不是重绘的 Markdown,而是引擎的真实画面。 监测器运行不请求页面,因此其回答没有页面。但只要有任务留下了页面,地址就会从该任务读回,仍可从回答打开。

成本与计划

一次运行会为参加该运行的每个引擎,按每个提示词、每个地点、每个样本各创建一个任务:
没有网格时 points 为 1。例如,12 个提示词分别发往 CHATGPT(1 积分)和 GOOGLE(1.25 积分),每次运行 24 个任务、27 积分;按每天一次计算, 每月约 810 积分。设置 "CHATGPT": { "samples": 5 } 后,同一监测器每次运行 72 个任务、75 积分。请从 GET /v1/monitors/capabilities 读取当前价格,而不要硬编码;积分如何冻结和扣除见积分与限制。 任务之外还有两项费用:
  • 竞争对手读取:每个监测器每 30 天 80 积分,按运行频率分摊到各次运行(每天运行的监测器每次约 2.67 积分,每周运行的约 18.67 积分)。 它在一次运行的任务全部提交后才收取,因此因余额不足而停下的运行不会为此付费。
  • 回答分析:设置 analysis: true 时,每个任务 1 积分,只对已分析的回答收费。评分(mentioned、cited、position)保持不变; 每个回答的结果在 GET /v1/monitors/{id}/answers/{taskId} 的 answer.analysis 中。
带 location 或 grid 的监控,每个任务加收 1 积分。 读取报告、来源、回答和结果不收费。
计划会一直重复,直到你暂停或删除监测器。上面的每月数字就是你在创建时承诺的成本。
计划的运行方式:
  • 一次运行不是瞬时爆发。 任务按套餐并发和引擎队列允许的速度提交。调度器每分钟从上次停下的位置继续,各引擎轮流各提交一个任务, 不同账户的监测器也轮流进行。母账户及其子账户共享同一组轮次。
  • 一次运行必须在其间隔内完成。 如果某个引擎的任务无法在该引擎下次运行前全部进入,创建和更新会返回 400 VALIDATION_ERROR,并给出可行的最短间隔。 满一个完整间隔后仍在提交的运行会被关闭,其余任务不再发送。
  • 错过的运行不会补跑。 nextRunAt 是下一次运行到期的时间。恢复已暂停的监测器或修改 intervalHours 时,下一次运行安排在此刻起一个间隔之后。

Capabilities

GET /v1/monitors/capabilities(参考)针对你的账户返回:每个可调度引擎及其 creditsPerTask、analysisCreditsPerTask、placeCreditsPerTask,你的 limits、modes、指标定义(metrics)、计划公式和变化事件类型。 它没有副作用,也不收费;以编程方式创建监测器之前请先调用它。

选择提示词

根据品牌信息建议提示词

POST /v1/monitors/suggest(参考)返回最多 12 个候选提示词,按 country 中购买者的提问方式写成。 它不保存任何内容,也不消耗积分。
例如:
包含品牌名称或别名的建议会被移除。创建监测器之前请检查这份列表。每 20 秒可请求一次建议,每小时 30 次;超出返回 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 来创建监测器;对于品类监测器,研究有多个核心时, 把每个提示词的 core 用作它在 promptTopics 中的条目,并把 brands[].brand 用作 competitors。在你创建监测器之前,什么都不会保存。 每次运行排入的任务不能超过账户的 tasksPerRun 限制,每个引擎按提示词 × 位置点 × samples 计数,因此请按你要创建的监测器设置 limit。 见从研究到监测器。

品类监测器

品类监测器为引擎在某个市场中提到的品牌排名。用 promptTopics 按细分领域为提示词分组:
品类监测器没有自己的品牌:aliases、domains 和 alertBelowPct 必须为空,否则请求返回 400 VALIDATION_ERROR,它也没有提醒。 它在 GET /v1/monitors 中的 stats.mentioned 和 stats.cited 始终为 0;列表会增加 leader,即最近 30 天被提到最多的品牌。 其报告见品类报告。计划、成本、来源、回答、结果和变化事件的工作方式与品牌监测器相同, 只是品类监测器只发送 monitor.source.first_cited 事件。 更新时,修改 prompts 会移除已删除提示词的 promptTopics 条目。这些提示词收集到的回答仍保留在排行榜中。

管理监测器

GET /v1/monitors/{id} 中的旧版周期摘要仅为兼容而保留。数字请使用 /analytics:旧版摘要把每个提示词和引擎最新回答的全时段矩阵混入窗口数字,把来源截断为 12 个域名和 20 个页面, 而且它的 shareOfVoice 按全部回答计算每个品牌,因此各份额相加可能超过 100。 属于其他账户的监测器返回 404 NOT_FOUND,而不是 403。

更新监测器

PATCH 接受创建字段的任意子集,并按相同限制对结果整体校验。省略的字段保持原值。
  • enabled: false 暂停监测器;enabled: true 恢复监测器,下一次运行安排在此刻起一个间隔之后。暂停在报告中显示为 pauses。
  • 修改 alertBelowPct 会重新启用提醒。
  • 修改别名、域名或竞争对手只影响此后评分的回答。已保存的回答保留评分时的定义,因此报告会扣留跨越该变更的比较(见 报告与指标)。

立即运行监测器

POST /v1/monitors/{id}/run 让下一次运行立即到期;调度器会在约一分钟内开始运行,并返回 data.queued: true。该运行与计划运行一样计费。 在该运行仍处于到期状态时再次调用,不会创建第二次运行。 排队前,该调用会检查你的余额是否足以支付这次运行,包括竞争对手读取和分析积分。不足时返回 402 INSUFFICIENT_CREDITS,并附带 details.needed 和 details.available。超出每月积分上限的子账户会收到 429 SUB_ACCOUNT_CREDIT_LIMIT。已暂停的监测器返回 404 NOT_FOUND:请先恢复它。

分享报告

你可以把一个监测器的报告发布在 https://querying.ai/<slug>。分享的报告展示分析、来源、引用、结果和回答; 永远不会展示设置、提醒、运行控制或你账户的任务健康状况。 GET /v1/monitors/{id}/share(参考)返回当前状态:access、slug、locale 和 url, 尚未设置 slug 时还会返回 suggestedSlug。PUT /v1/monitors/{id}/share(参考)用于修改:
把 access 设为 PRIVATE 会让报告下线并保留 slug,因此再次开启分享时会沿用同一地址。

从智能体使用监测器

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:在花费任何积分之前了解引擎、价格和限制。
  2. GET /v1/monitors:复用针对该主题和市场的监测器,或新建一个,可以从 POST /v1/monitors/suggest 开始。
  3. 只有在下一次计划运行之前就需要回答时,才调用 POST /v1/monitors/{id}/run。
  4. GET /v1/monitors/{id}/analytics?days=30:先读 quality 再读数字,并等到 health.pending 变为 0。
  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=...&format=csv:导出同一窗口,沿着 x-next-cursor 读到它为空。

限制

合同账户是指协商了并发上限的账户。以下限制适用于所有账户: 报告、分页大小和保留期限制列在使用它们的页面上: 报告与指标、来源与回答和 事件与提醒。

错误

错误信封与其他地方相同(见错误)。监测器特有的错误码:

后续步骤

报告与指标

/analytics 协议以及每个数字的含义。

来源与回答

被引用的页面、每个评分背后的回答,以及导出。

事件与提醒

回答变化时的 Webhook,以及基于提及率的邮件提醒。

Prompt Research

根据搜索需求找出值得跟踪的提示词。