Pings

GET/api/v1/pings

Reads probe history initiated by a specific VPS Agent from its own network position. This source is independent of Cloudflare active checks and External Latency Agents.

Target protocols

The admin UI keeps existing target fields. Since Agent v1.0.44, the scheme selects the probe method:

Syntax	Protocol	Success condition
host:port	TCP	TCP connect within 1 s
tcp://host:port	TCP	TCP connect within 1 s
http://host/path	HTTP	200-399 response within 1 s
https://host/path	HTTPS	200-399 response within 1 s

Targets must not contain HTTP usernames or passwords. The Agent advertises tcp,http; 1.0.44 no longer accepts new icmp:// targets, and legacy ICMP targets are not distributed.

Query parameters

Parameter	Required	Default	Purpose
agent_id	yes	empty	the Agent that runs the probes
hours	no	24	default max 72 h, deployment cap 168 h
max_points_per_target	no	360	points per target on regular curves; non-positive falls back, hard cap 2000
format	no	row	series returns compact per-target series
include_loss	no	0	1 returns all raw loss events losslessly in the window

curl -fsSL 'https://YOUR-API/api/v1/pings?agent_id=vps-a&hours=6&format=series&include_loss=1'

Response fields

Field	Purpose
targets[]	enabled target IDs, names, colors
pings[]	bounded row history; empty with format=series
series	bounded compact curves per target
ping_stats	totals, successes, loss rate from raw pre-downsampling samples
pings_raw_count	points before downsampling
pings_downsampled	whether regular curves were downsampled
ping_interval_sec	current global probe interval
loss_series	lossless loss runs when include_loss=1
loss_events_raw_count	raw loss events represented by loss_series
source	current history source

loss_series[] uses { target_id, t0, runs }; each run is [start_delta, step, count] with timestamps t0 + start_delta + step * index (index from 0 to count - 1). Sparse losses are not dropped. The built-in frontend no longer draws this layer but shows per-target loss via ping_stats.

Failed points have latency_ms: null; never interpret as 0 ms. R2 keeps raw telemetry as the authoritative history; optional timeseries export does not change this endpoint, and export failures never block Agent ACK or R2 archiving.

Display advice

• Legend uses targets[] names; data links by ID.
• Latency curves use bounded series; per-target summaries use ping_stats.
• For complete loss events, request include_loss=1 and read loss_series.
• No new probes while the Agent is offline is expected.
• Do not merge Pings with other sources into label-less curves.