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
integer
default:"24"
The 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
object
Three time series, each an array of
[unixSeconds, value] pairs in ascending time order.object
The instance’s configured shape in the same units:
cpu_cores, memory_bytes, disk_bytes. Chart these as ceilings over the series.integer
The window that was returned.
integer
Spacing 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.
integer
When the query ran, in epoch seconds.
404 not_found. If the metrics store is unreachable, you get 503 try_again; retry shortly.
Example
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.