Checks

GET/api/v1/checks

读取单个目标的可用性记录、每日点与对应 Agent 在线序列，适合 SLA 日格、延迟折线与故障时间轴。

查询参数

参数	必填	默认	范围	说明
target_id	是	—	有效公开目标 ID	目标标识
hours	否	72	1–720	历史窗口，最大 30 天
limit	否	864	上限 12000，部署可在 100–20000 调整	最大检查点数

curl -fsSL 'https://YOUR-API/api/v1/checks?target_id=vps-a&hours=72&limit=864'

响应结构

{
  "ok": true,
  "source": "d1-check-buckets",
  "checks": [],
  "daily_points": [],
  "agent_series": []
}

字段	说明
checks[]	过滤到时间窗口、按新到旧返回的 Cloudflare 检查点
daily_points[]	从检查桶计算的日级展示数据
agent_series[]	对应 Agent 的在线历史，不等同于 Cloudflare 检查
source	当前历史存储来源

缺少 target_id 返回 HTTP 400。不存在、禁用或隐藏公网地址的目标可能返回空历史；结合 Status 的目标清单与隐私字段判断，不要自动切换到 Admin API。

绘图建议

1. 收到数据后按 checked_at 升序复制一份用于折线图。
2. ok = false 的点不要伪造延迟为 0。
3. 缩放重置时把坐标范围设回实际首尾时间戳。
4. 数据不足两个点时显示单点状态，不拉伸成趋势。
5. Cloudflare 检查与 agent_series 用不同图例与状态说明。

缓存

规范化后的 target_id、hours 与 limit 纳入缓存键，相同查询命中短缓存。默认约 60 秒，部署可在 0–300 秒调整。响应携带 X-NIE-SLA-Cache: hit|miss，并在 v1 内继续发送旧 X-NStatus-Cache。不要用无意义参数绕过缓存。