GET /api/vms/{id}/metrics/history

Read the per-VM resource curves the host records for a classic VM. AppVM ids belong to GET /api/appvm/vms/{id}/metrics/history.

Samples are stored in a round-robin database, so older windows are returned at a coarser resolution rather than dropped. Always read interval_secs from the response instead of assuming a step: the host picks the finest resolution that covers the requested window.

Property	Value
Scope	read
Request body	none
Success	200 OK

Endpoint

GET ${baseUrl}/api/vms/${id}/metrics/history

read

Read a classic VM's CPU, memory, disk, and network history.

Use your host URL and API key as shell variables:

baseUrl="https://agent.example.com"
VIRT_AGENT_API_KEY="<your-api-key>"

cURL template

curl --request GET "${baseUrl}/api/vms/${id}/metrics/history" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

Request

Location	Name	Type	Required	Description
Header	Authorization	bearer token	yes	Bearer ${VIRT_AGENT_API_KEY}.
Path	id	string	yes	VM id.
Query	range	string	no	Window ending now. One of 1h, 24h, 7d, 30d, 1y. Defaults to 1h. Any other value is rejected with 400.
Query	from	integer	no	Window start as a Unix timestamp in seconds. Must be sent together with to.
Query	to	integer	no	Window end as a Unix timestamp in seconds. Must be sent together with from.

from and to select an exact window and override range. Sending only one of the pair is rejected with 400.

Response

Returns one VmMetricsHistory object. A VM with no samples yet returns an empty points array rather than 404.

Field	Type	Presence	Description
points	array of VmMetricPoint	always	Samples in ascending time order. Empty when nothing is recorded for the window.
interval_secs	integer	always	Seconds between samples in this response. 0 when points is empty.

points[] (VmMetricPoint)

Field	Type	Presence	Description
ts	integer	always	Sample time as a Unix timestamp in seconds.
cpu_pct	number	always	CPU use as a percentage of the VM’s own vCPU allowance, so a fully loaded VM reads about 100 regardless of its vCPU count.
cpu_pct_max	number	always	Peak within the same bucket. Equal to cpu_pct at the finest resolution; it separates from the average only in coarser windows, where it preserves spikes averaging would hide.
mem_rss_mb	integer	always	Resident memory in MiB.
disk_read_bps	integer	always	Root-disk read throughput in bytes per second.
disk_write_bps	integer	always	Root-disk write throughput in bytes per second.
net_in_bps	integer	always	Bytes per second the guest received.
net_out_bps	integer	always	Bytes per second the guest sent.

Examples

Call example

baseUrl="https://agent.example.com"
VIRT_AGENT_API_KEY="<your-api-key>"
id="demo-api-vm"

curl "${baseUrl}/api/vms/${id}/metrics/history?range=1h" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

Zoom into an exact window instead:

curl --get "${baseUrl}/api/vms/${id}/metrics/history" \
  --data-urlencode "from=1785312000" \
  --data-urlencode "to=1785315600" \
  --header "Authorization: Bearer ${VIRT_AGENT_API_KEY}"

Response example

{
  "points": [
    {
      "ts": 1785312000,
      "cpu_pct": 12.5,
      "cpu_pct_max": 12.5,
      "mem_rss_mb": 1180,
      "disk_read_bps": 0,
      "disk_write_bps": 262144,
      "net_in_bps": 1024,
      "net_out_bps": 4096
    },
    {
      "ts": 1785312010,
      "cpu_pct": 41.0,
      "cpu_pct_max": 41.0,
      "mem_rss_mb": 1183,
      "disk_read_bps": 0,
      "disk_write_bps": 131072,
      "net_in_bps": 2048,
      "net_out_bps": 8192
    }
  ],
  "interval_secs": 10
}

Errors

Status	Code	Description
400	BAD_REQUEST	range is not one of the accepted values, or only one of from and to was sent.
401	UNAUTHORIZED	API key is missing or invalid.
403	FORBIDDEN	API key is valid but not allowed to access the endpoint.
404	NOT_FOUND	No classic VM exists with id.