Pings
GET
/api/v1/pings读取指定 VPS Agent 从自身网络位置发起的探测历史。该数据源与 Cloudflare 主动检查及 External Latency Agent 相互独立。
目标协议
后台继续使用现有目标字段。Agent v1.0.44 起按目标 scheme 选择探测方式：
| 写法 | 协议 | 成功条件 |
|---|---|---|
host:port | TCP | 1 秒内建立 TCP 连接 |
tcp://host:port | TCP | 1 秒内建立 TCP 连接 |
http://host/path | HTTP | 1 秒内收到 200-399 响应 |
https://host/path | HTTPS | 1 秒内收到 200-399 响应 |
目标不得包含 HTTP 用户名或密码。Agent 声明 tcp,http 能力；1.0.44 不再接受新的 icmp:// 目标，遗留 ICMP 目标不下发。
查询参数
| 参数 | 必填 | 默认 | 说明 |
|---|---|---|---|
agent_id | 是 | 空 | 执行探测的 Agent ID |
hours | 否 | 24 | 默认最大 72 小时，部署上限 168 小时 |
max_points_per_target | 否 | 360 | 常规曲线每目标点数；非正值回默认，硬上限 2000 |
format | 否 | 行格式 | series 返回按目标分组的紧凑序列 |
include_loss | 否 | 0 | 1 时无损返回所选时间范围内的全部原始丢包事件 |
bash
curl -fsSL 'https://YOUR-API/api/v1/pings?agent_id=vps-a&hours=6&format=series&include_loss=1'响应字段
| 字段 | 说明 |
|---|---|
targets[] | 当前启用的探测目标 ID、名称与颜色 |
pings[] | 行格式的有界历史点；format=series 时为空 |
series | 按目标组织的有界紧凑曲线 |
ping_stats | 按降采样前原始样本计算的总数、成功数与丢包率 |
pings_raw_count | 降采样前总点数 |
pings_downsampled | 常规曲线是否已按目标降采样 |
ping_interval_sec | 当前全局探测间隔 |
loss_series | include_loss=1 时返回的无损丢包 runs |
loss_events_raw_count | loss_series 表示的原始丢包事件总数 |
source | 当前历史来源 |
loss_series[] 使用 { target_id, t0, runs }。每个 run 为 [start_delta, step, count]，时间戳为 t0 + start_delta + step * index（index 从 0 到 count - 1）。该表示不丢弃稀疏丢包。内置前端不再绘制该图层，但通过 ping_stats 显示每目标丢包率。
失败点的 latency_ms 为 null，不得解释为 0 ms。R2 默认保存原始遥测并作为权威历史来源；可选时序导出不改变本接口，导出失败不阻塞 Agent 确认或 R2 归档。
展示建议
- 图例显示
targets[]名称，数据关联使用 ID。 - 延迟曲线用有界
series，目标摘要用ping_stats显示丢包率。 - 需要完整丢包事件时显式请求
include_loss=1并读取loss_series。 - Agent 离线期间没有新探测属于预期行为。
- 不要把 Pings 与其他观测来源合并成缺少来源标签的曲线。