API reference

Machine metrics API

Read a machine's CPU, memory, disk, I/O, and network history at one-minute resolution, or the host's live samples.

Get machine metrics: GET /v1/machines/{machine_id}/metrics

Get machine metrics

GET /v1/machines/{machine_id}/metrics

resolution=1m (the default) reads stored one-minute history, at most 1440 points per response; continue with next_since. resolution=live relays the host's samples and needs a running or sleeping machine (409 machine_not_running); fall back to 1m on 409 or 503. See Machine metrics.

API key: Authorization: Bearer vmy_… with preset read_only, use_existing, create_and_use, full_access.
Browser session: the vmyard_session cookie.
Who: Any member.

Parameters

Name	In	Type	Required	Description
`machine_id`	path	`string (uuid)`	Yes
`X-Organization-ID`	header	`string (uuid)`	No	Required with a browser session. Optional with an API key, which fixes the organization; when sent it must match.
`resolution`	query	`string`	No	`1m` (default; stored history) or `live` (the host's samples through the fleet).
`since`	query	`string`	No	Only points at or after this time (UTC RFC 3339). Defaults to the last 24 hours for `1m` and everything the host keeps for `live`.

Responses

Status	Description	Body
`200`	—	`MachineMetricsDto`
`401`	Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`).	`ProblemDetails`
`404`	Not found in this organization (`resource_not_found`).	`ProblemDetails`
`409`	`machine_not_running`: `live` needs a running or sleeping machine	`ProblemDetails`
`422`	An unknown `resolution` or a malformed `since`	`ProblemDetails`
`503`	`metrics_unavailable` (no runtime configured for `live`) or `runtime_unavailable`	`ProblemDetails`

Request

curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/metrics" \
  -H "Authorization: Bearer $VMYARD_API_KEY"

Response 200

{
  "cpu_limit_millis": 0,
  "guest_reported": {
    "filesystem_available_bytes": 0,
    "filesystem_total_bytes": 0,
    "memory_available_bytes": 0,
    "memory_total_bytes": 0,
    "reported_at": "2026-10-12T05:51:01Z"
  },
  "interval_ms": 0,
  "machine_id": "6f1c2d3e-4b5a-4c7d-8e9f-0a1b2c3d4e5f",
  "memory_limit_bytes": 0,
  "next_since": "string",
  "points": [
    {
      "cpu_millis": 0,
      "cpu_millis_max": 0,
      "cpu_percent": 0.5,
      "disk_percent": 0.5,
      "disk_used_bytes": 0,
      "io_read_bps": 0,
      "io_write_bps": 0,
      "memory_bytes": 0,
      "memory_bytes_max": 0,
      "memory_percent": 0.5,
      "net_rx_bps": 0,
      "net_tx_bps": 0,
      "t": "2026-10-12T05:51:01Z"
    }
  ],
  "resolution": "live"
}