Latency

GET/api/v1/latency

读取多个外部 Latency Agent 到指定公开 TCP 目标的历史。Cloudflare 自身延迟不在此响应中，从 Status 或 Checks 获取。

查询参数

参数	必填	默认	范围	说明
target_id	是	—	公开 TCP 目标 ID	被探测目标
hours	否	24	1–168	历史窗口

curl -fsSL 'https://YOUR-API/api/v1/latency?target_id=vps-a&hours=24'

响应结构

{
  "ok": true,
  "target_id": "vps-a",
  "sources": [
    {
      "id": "home-shanghai",
      "name": "Shanghai Telecom",
      "kind": "external",
      "points": [
        {
          "checked_at": 1760000000,
          "latency_ms": 28.4,
          "ok": true
        }
      ]
    }
  ]
}

sources[]

每个来源对应后台创建并实际成功上报的 Latency 节点。创建节点记录本身不产生数据；安装命令完成首次提交后节点才进入历史响应。

缺少 target_id、目标不存在或已停用时，兼容实现可能用 HTTP 200 返回 ok: false 与 error。客户端必须检查 JSON ok。

Status 中的 latency_sources 只保留仍在 stale 窗口内的最新来源；本端点按 hours 返回保留期内历史。“历史里有旧点，但当前图例不显示节点”通常是节点已停止上报。

排障顺序

如果前端只有 Cloudflare：

1. 后台检查节点是否启用且“最近上报”非空。
2. 在节点检查 systemd 服务与 journal。
3. 手动运行一次 --once，确认 accepted 大于 0。
4. 确认目标是启用的公开 TCP 目标，且未隐藏公网地址。
5. 等待状态短缓存刷新，再检查本端点是否出现 sources。

部署新命令时安装器清理所有旧进程；旧节点只重启可能继续使用过期脚本、节点 ID 或 Token。

本端点默认缓存 30 秒，target_id 与 hours 进入缓存键。只返回外部 Latency 来源；Cloudflare 当前延迟来自 Status，历史来自 Checks。