Read metrics
Fetch an instance's CPU, memory, and disk history to see whether it is sized right, spot leaks, and know before it hits a limit.
GET /v1/instances/{id}/metrics returns up to 14 days of resource history: CPU cores in use, memory bytes, and disk bytes, sampled about once a minute on the host, alongside the instance's configured limits. Where logs answer "what did it print", metrics answer "is it running out of something": a memory line creeping toward its limit, CPU pinned at the cap, or a disk filling up.
Samples start landing a couple of minutes after an instance first runs, so a just-created instance answers 200 with empty series at first. While an instance is sleeping or stopped there is no live container to measure: CPU and memory show gaps for those periods, and only disk keeps reporting.
Request
24The window to return, ending now. Defaults to 24, capped at 336 (14 days, which is also the retention). A value that is not an integer in range returns 400 invalid_request.
Response
seriesobjectThree time series, each an array of [unixSeconds, value] pairs in ascending time order.
series
cpu_coresarrayCPU in use, in cores (for example 0.4 on a 2-vCPU instance means 20% of one core). Compare against limits.cpu_cores.
memory_bytesarrayMemory in use, in bytes.
disk_bytesarrayDisk used by the instance's data volume, in bytes.
limitsobjectThe instance's configured shape in the same units: cpu_cores, memory_bytes, disk_bytes. Chart these as ceilings over the series.
hoursintegerThe window that was returned.
step_secondsintegerSpacing between points. It widens with the window (60s at one hour, coarser at 14 days) so any range returns a chart-sized payload of a few hundred points.
fetched_atintegerWhen the query ran, in epoch seconds.
Unknown, deleted, or other-workspace ids return 404 not_found. If the metrics store is unreachable, you get 503 try_again; retry shortly.
Example
curl "https://api.pusk.ai/v1/instances/ab12cd34ef/metrics?hours=24" \
-H "Authorization: Bearer sk_live_..."
Reading the numbers
- Memory near its limit: an agent that keeps climbing toward
limits.memory_byteswill eventually be killed and restarted (that shows up in logs as a risingrestart_countand a"critical"memory verdict). Resize before it gets there. - CPU pinned at the limit: sustained
cpu_coresatlimits.cpu_coresmeans the agent is throttled and everything it does is slower. Resize, or give it less concurrent work. - Disk trending up: disk is the one series that never resets on restart. A steady climb is usually accumulated artifacts or caches; clean up over exec, or resize for more disk.
The same charts live in the dashboard on the instance's Metrics tab.