# 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-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](/docs/guides/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`](/docs/api/schemas#machinemetricsdto) |
| `401` | Not signed in, or the API key is malformed, expired, or revoked (`unauthenticated`, `invalid_api_key`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `404` | Not found in this organization (`resource_not_found`). | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `409` | `machine_not_running`: `live` needs a running or sleeping machine | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `422` | An unknown `resolution` or a malformed `since` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |
| `503` | `metrics_unavailable` (no runtime configured for `live`) or `runtime_unavailable` | [`ProblemDetails`](/docs/api/schemas#problemdetails) |

```sh title="Request"
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID/metrics" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```json title="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"
}
```