Metrics

GET/api/v1/metrics

Reads the latest state and history of one Rust Agent. History comes from R2 first and is downsampled to the requested cap; unlimited raw history is not returned.

Query parameters

Parameter	Required	Default	Purpose
agent_id	yes	deployment default agent if set	usually matches the VPS target ID
hours	no	24	default max 72 h, deployment-adjustable 1–168
max_points	no	window-based	returned points; non-finite, 0, or negative fall back to safe defaults, minimum 60
history	no	1	0 reads latest only
format	no	row	columns returns compact columnar series
metric / fields	no	all	restrict metric groups or fields

curl -fsSL 'https://YOUR-API/api/v1/metrics?agent_id=vps-a&hours=6&max_points=360'

Optional metrics

Groups: cpu, mem, disk, load, net, conns, diskio, temp, gpu. Or comma-separated fields:

cpu,mem,disk,load1,net_rx,net_tx,tcp_conns,udp_conns,
disk_read,disk_write,cpu_temp,gpu_temp,gpu_util,
motherboard_temp,disk_temp,chipset_temp

curl -fsSL 'https://YOUR-API/api/v1/metrics?agent_id=vps-a&hours=1&fields=cpu,mem,cpu_temp'

Response fields

Field	Purpose
latest	latest agent summary; null before first report
history[]	ascending row history; empty in columnar format
series	t0, dt, fields, and value arrays for format=columns
history_raw_count	points before downsampling
history_downsampled	whether downsampled
source	r2, r2+d1-fallback, d1, etc.
traffic	current billing-period traffic summary
warnings[]	non-blocking warnings about latest state or history

Columnar format

{
  "series": {
    "t0": 1760000000,
    "dt": [0, 10, 20],
    "fields": ["cpu", "mem"],
    "values": {
      "cpu": [8.4, 9.1, 7.8],
      "mem": [42.0, 42.1, 42.1]
    }
  }
}

Each timestamp is t0 + dt[index]. Clients must check every values array length; do not assume proxies return complete columns.

history=0 skips history reads, suitable for latest-only views. With format=columns, history is empty and data lives in series; do not consume both. The server normalizes agent ID, window, points, format, and fields into the cache key.

Units and nulls

Units follow current frontend display and response semantics. Temperature, GPU, motherboard, and disk sensors are unavailable in most virtualized environments; hide missing series instead of showing 0°C.

latest.vps_info.total_disk_gb is the root filesystem capacity. Network and disk IO are rate fields; billable traffic comes from the persisted period ledger, never from a single net_rx/net_tx sample.