/v1/monitors 端点,你可以创建在固定时间表上运行的持久监控器,检测页面变化,并通过电子邮件、Slack、短信或专用的 webhook 通知你。
- 从自然语言
query创建监控器 - 使用
source_policy限制来源 - 在自然语言时间表上运行检查(最小每 10 分钟一次,UTC)
- 配置
notification.channels和可选的webhook传递 - 使用服务器发送事件(
?stream=1)流式传输配置进度 - 列出、检查、更新、暂停、恢复和删除监控器
- 读取快照事件、计划工件、运行日志和实时代理日志
query 中表达这一意图。
安装
创建监控器
使用POST /v1/monitors 创建监控器。API 验证你的输入,保留一个监控器记录,配置一个影子代理,生成一个工作流规范,排队 DAG 计划,并创建一个重复的时间表。
query是必需的——用自然语言描述要监控的内容。frequency是可选的,默认为every hour。使用诸如every day at 9am的调度短语(调度在 UTC 中运行;最小间隔为 10 分钟)。source_policy可选地限制include_urls、exclude_urls、include_domains和exclude_domains。notification配置何时以及如何提醒(events+channels)。频道传递在运行时由监控器管道解析——你无需将接收者传递到 DAG。webhook是一个单独的对象({ "url": "https://…" }),用于 HTTP 回调,除了notification.channels之外。output_schema可选地强制执行结构化提取(有效的 JSON Schema)。
202,状态为 provisioning。监控器在计划解决 tracked 目标后转为 active。轮询 GET /v1/monitors/:monitor_id 或传递 ?stream=1(或 Accept: text/event-stream)以通过 SSE 跟踪配置阶段和规范推理令牌。
示例请求
你只需要query 和 frequency。通知频道和 webhooks 可以稍后通过 POST /v1/monitors/:monitor_id 添加。
响应
成功创建(非流式)返回 HTTP202 和一个监控器对象。在计划完成之前,tracked 是空的;轮询 GET /v1/monitors/:monitor_id 直到 status 是 active 并且 tracked.urls 被填充。
结构化监控器输出
当你希望提取结果遵循特定的 JSON 结构时,设置output_schema。该模式必须是有效的 JSON Schema。
配置流
添加?stream=1 或发送 Accept: text/event-stream 以在创建监控器时接收 SSE 事件:
| 事件 | 描述 |
|---|---|
phase | 配置步骤(running、done 或 failed) |
reasoning_token | 增量规范设计文本 |
reasoning_reset | 在 LLM 尝试失败后截断缓冲的推理 |
complete | 最终监控器对象(与 202 响应相同的形状) |
error | 终端失败 |
通知和 webhooks
警报在监控器记录上配置,并在运行时解析——不要在监控query 中嵌入频道目标。
notification
| 字段 | 描述 |
|---|---|
events | 哪些运行结果应触发传递。请参阅下面的通知事件。如果你设置了 channels 并省略了 events,则默认为 changed 和 first_snapshot。 |
channels | { "type", "target", "events"? } 对象列表 |
通知事件
使用events 来说明你希望何时收到通知。允许的值:
| 事件 | 含义 |
|---|---|
changed | 当监控器检测到与前一个快照相比的变化时通知(例如新内容、更新价格或管道分类为已更改的差异)。 |
first_snapshot | 当监控器拍摄其第一次快照时通知——存储当前内容的初始基线运行,以便以后进行比较。 |
["changed"] 仅在基线之后的更新时提醒;["first_snapshot"] 确认设置而无需等待差异;["changed", "first_snapshot"] 覆盖两者。
频道对象上的每个频道 events 使用相同的值,并仅为该频道覆盖顶级列表。
支持的频道类型:
type | target 格式 |
|---|---|
email | 有效的电子邮件地址 |
slack | Slack 入站 webhook URL |
sms | E.164 电话号码(例如 +14155552671) |
webhook
与 notification.channels 分开,webhook.url 在监控器触发你的回调 URL 时接收 HTTP POST 负载。你可以在同一个监控器上同时使用 webhook 和频道通知。
示例
仅电子邮件:来源策略
使用source_policy 来限制计划者可以使用的 URL 和域。
频率
以自然语言设置frequency,例如:
every hour(省略时的默认值)every day at 9amevery weekday at 14:30
- 必须读作调度语言(而不是任意的监控问题)。
- 最小间隔:每 10 分钟。
- 调度存储并在 UTC 中执行(
schedule.timezone是UTC)。 - 最大长度:50 个字符。
frequency 文本中派生出一个 cron 表达式,并在 schedule.cron 上暴露出来。当监控器为 active 时,schedule.next_run_at 显示 ISO 8601 格式的下一次运行。
列出监控器
使用GET /v1/monitors 检索你的团队的所有监控器。
默认情况下,已删除的监控器被过滤掉。使用 ?include_deleted=true 来包含它们。
响应形状
获取监控器
使用GET /v1/monitors/:monitor_id 检索单个监控器。
响应包括 last_run(最新快照摘要)和 total_count(快照计数),除非你传递 include_total_count=false。添加 include-diagram=true 以包含监控器 DAG 的 mermaid_diagram。
响应形状
列出监控器事件
使用GET /v1/monitors/:monitor_id/events 列出监控器的快照事件。
分页:
limit(默认25,最大100)cursor(来自next_cursor的不透明令牌)count_only=true仅返回{ "total_count": N }
snapshot_url。
响应形状
获取监控器计划
使用GET /v1/monitors/:monitor_id/planning 检查 FDA 工作流规范和计划 DAG 在配置后的状态。
获取监控器运行
使用GET /v1/monitors/:monitor_id/runs/:run_id 获取一次执行的快照元数据和解析的代理日志事件(run_id 必须以 run_ 开头)。
流式代理日志
使用GET /v1/monitors/:monitor_id/agent-logs?stream=1(或 Accept: text/event-stream)来跟踪监控器代理的 CloudWatch 日志,过滤到此 monitor_id。
可选查询参数 since 是一个毫秒时间戳(默认:30 分钟前)。
SSE 事件类型:ready、log、heartbeat、error。
更新监控器
使用POST /v1/monitors/:monitor_id 更新监控器。
支持的字段(仅包含你想更改的内容):
metadata— 与现有键合并;空字符串值删除键frequency— 重新创建内部时间表并将status设置回activenotification— 替换整个通知对象webhook— 传递null以移除
status 为 provisioning 时返回 409。
当你添加 notification.channels 而没有 events 时,API 默认 events 为 ["changed", "first_snapshot"]。
添加电子邮件通知
添加 webhook
暂停监控器
使用POST /v1/monitors/:monitor_id/pause 暂停监控器。
暂停会禁用底层时间表并将 status 设置为 paused。只有 status: active 的监控器可以暂停。请求体为空。
200 和监控器及 status: paused。暂停时,schedule.next_run_at 为 null。
恢复监控器
使用POST /v1/monitors/:monitor_id/resume 恢复暂停的监控器。
恢复会重新启用时间表并将 status 设置回 active。只有 paused 的监控器可以恢复。
删除监控器
使用DELETE /v1/monitors/:monitor_id 删除监控器。
删除会软删除监控器行(status: deleted)并移除其时间表和影子代理资源。
监控器状态
| 状态 | 含义 |
|---|---|
provisioning | 代理、规范、计划者和时间表正在设置中 |
active | 时间表启用;运行在 schedule.frequency 上执行 |
paused | 通过 /pause 禁用时间表 |
failed | 配置或时间表更新失败(error_message 已设置) |
deleted | 通过 DELETE 软删除 |
示例用例
以下是常见的监控器模式。每个示例在创建时只需要query 和 frequency;如果你想在第一次运行或变化时收到警报,可以稍后添加 notification 和 webhook。
Y Combinator 新发布
监控 Y Combinator Launches 上新发布的创业公司。在计划之后,tracked.type 是 urls,tracked.urls 指向发布页面。
active 后添加电子邮件和 webhook 传递:
channels 并省略了 events,API 默认为 ["changed", "first_snapshot"],因此你会在基线运行和检测到变化时收到通知。
竞争对手博客文章(AirOps,Profound)
监控竞争对手博客索引以获取新文章。计划者将tracked.urls 解析为博客 URL(例如 https://www.airops.com/blog 或 https://www.tryprofound.com/blog)。
notification 上使用 events: ["changed"]。
股票价格阈值(特斯拉)
当条件是数字而不是页面差异时,监控结构化数据源。计划者将tracked.type 设置为 data_api 并将 tracked.urls 留空。
OpenAI API 更新日志
当 OpenAI 的 API 更新日志 列出新功能、模型发布或弃用时收到通知。在query 中提到更新日志 URL 或使用 source_policy.include_urls 固定它。
events 设置为 ["changed"],这样当更新日志内容发生变化时你会收到警报,而不仅仅是在存储第一次快照时。
管理多个监控器
列出你的团队的所有监控器,以便在一个地方查看状态、时间表和已解析的目标:data_api 价格监控,以及配置了电子邮件和 webhook 的 YC 发布监控——响应中 "count": 4(或更多)。
常见验证错误
监控器端点为常见的无效请求返回明确的验证错误:- 缺少或空的
query frequency不是调度语言,解析过于频繁(低于 10 分钟)或超过 50 个字符- 无效的
source_policy条目(URL 数组必须包含有效的http/https字符串) - 无效的
notification形状,未知的events,或无效的频道type/target - 无效的
webhook.url(必须是http或https) - 无效的
output_schema(必须是有效的 JSON Schema) - 无效的
monitor_id或run_id格式 - 当
status为provisioning时更新(409) - 当状态不是
active/paused时暂停/恢复