# Read a Computer's usage

URL: https://heaven.dev/docs/reference/computers/usage
Updated: 2026-11-21

Read CPU, memory, disk and network history for one Computer. Without a Computer, read CPU and memory across accessible Computers.

`GET /v1/computer/?view=usage`

## Parameters

- `computer` (string): Computer name or ID.
- `range` (string): History period: 24h (default), 7d or 30d.
- `resolution` (string): Interval between usage points. Give 1m, 5m or 1h. This interval takes precedence over `points`. When both fields are omitted, one Computer or a pool uses 5m for 24h and 1h for longer ranges. A list of Computers uses 1h.
- `points` (string): Target maximum number of points per series, from 1 to 1000. A series includes at least one point per day. MCP defaults to 24 points. An explicit `resolution` overrides this target.
- `organization` (string): Organization name or ID. A credential, named resource or sole membership can select the organization for you.
- `pool` (string): Pool name or ID to filter the Computer list. Applies to a list without a named Computer.

## Returns

- `data` (object, always present): One Computer's usage history, or CPU and memory history for accessible Computers in the selected scope.
  - `alternative-1` (object): A Computer's usage history.
    - `range` (string, always present): Selected history range.
    - `resolution_seconds` (integer, always present): Duration of each series interval in seconds.
    - `series` (object[], always present): Usage intervals in time order, using summary measures and units. `bucket_start` identifies the interval; unmeasured values are omitted.
      - `items` (object): Measurements for one interval. Unmeasured values are omitted.
    - `summary` (object, always present): Usage over the range; null measurements are unknown.
      - `bucket_start` (string (date-time), always present): Start of the interval.
      - `computer_id` (string, always present): Measured Computer's ID.
      - `covered_seconds` (number, always present): Seconds covered by CPU and memory measurements.
      - `cpu_usec` (integer | null, always present): CPU time consumed, in microseconds.
      - `cpu_vcpus_avg` (number | null, always present): Average vCPUs in use over measured time.
      - `cpu_vcpus_max` (number | null, always present): Peak measured vCPUs in use.
      - `disk_size_bytes` (integer | null, always present): Logical disk size in bytes.
      - `disk_used_bytes` (integer | null, always present): Measured disk use in bytes.
      - `egress_bytes` (integer): Bytes sent directly to the internet. May be omitted.
      - `front_door_bytes` (integer): Bytes sent to visitors through Heaven's front doors. May be omitted.
      - `io_covered_seconds` (number, always present): Seconds covered by disk I/O measurements.
      - `io_read_bytes` (integer | null, always present): Bytes read from disk.
      - `io_read_ops` (integer | null, always present): Disk read operations counted.
      - `io_write_bytes` (integer | null, always present): Bytes written to disk.
      - `io_write_ops` (integer | null, always present): Disk write operations counted.
      - `memory_bytes_avg` (number | null, always present): Average measured memory use in bytes.
      - `net_covered_seconds` (number, always present): Seconds covered by network measurements.
      - `net_rx_bytes` (integer | null, always present): Bytes received by the Computer.
      - `net_tx_bytes` (integer | null, always present): Bytes sent by the Computer.
      - `pool_id` (string): Pool containing the Computer when measured. May be omitted.
      - `running` (boolean, always present): Whether the Computer was recorded running in the interval.
      - `vcpus` (integer, always present): Recorded vCPU count.
  - `alternative-2` (object): CPU and memory history for Computers you own or can access as Root in the selected scope.
    - `computers` (object[] | null, always present): A summary and series for each measured Computer.
      - `items` (object): One Computer's CPU and memory history.
        - `id` (string, always present): Computer ID.
        - `name` (string, always present): Computer name.
        - `series` (object[] | null, always present): One point per interval since the Computer was created.
          - `items` (object): Average CPU and memory use over an interval. Unmeasured values are omitted.
            - `cpu_vcpus_avg` (number): Average vCPUs in use over measured time. May be omitted.
            - `memory_bytes_avg` (number): Average memory use in bytes. May be omitted.
            - `start` (string (date-time), always present): Start of the interval.
        - `summary` (object, always present): Average measured usage over the selected range.
          - `cpu_vcpus_avg` (number): Average vCPUs in use over measured time. May be omitted.
          - `memory_bytes_avg` (number): Average memory use in bytes. May be omitted.
          - `start` (string (date-time), always present): Start of the interval.
    - `range` (string, always present): Selected history range.
    - `resolution_seconds` (integer, always present): Duration of each series interval in seconds.

## Errors

Each code is explained in full at https://heaven.dev/docs/reference/errors.

| Code | Status | What happened |
|---|---:|---|
| `invalid` | 400 | An input is missing or invalid. |
| `unauthenticated` | 401 | The credential is missing, invalid, expired or revoked. |
| `denied` | 403 | The caller lacks permission for this action. |
| `not_found` | 404 | The resource is absent or inaccessible to this caller. |
| `conflict` | 409 | The request conflicts with the current resource state or an earlier request. |
| `over_capacity` | 409 | The request exceeds a resource or credential allowance. |
| `access_list_full` | 409 | The change would exceed the access-list allowance. |
| `rate_limited` | 429 | The caller's request rate exceeds its limit. |
| `busy` | 429 | Too much work is in progress to accept this request. |
| `unknown` | 503 | The outcome is unconfirmed; a change may have happened. |
| `unavailable` | 503 | The service or requested feature is unavailable. |

## Notes

- API key permission: `usage`.

## Examples

```sh tab="heaven CLI"
heaven usage [COMPUTER]
  [--range 24h|7d|30d]
  [--resolution 1m|5m|1h]
  [--points N]
  [--organization ORGANIZATION]
  [--pool POOL]
```

```sh tab="SSH"
ssh cli@heaven.dev usage [COMPUTER]
  [--range 24h|7d|30d]
  [--resolution 1m|5m|1h]
  [--points N]
  [--organization ORGANIZATION]
  [--pool POOL]
```

```sh tab="cURL"
curl "https://heaven.dev/v1/computer/?view=usage&computer=my-site" \
  -H "Authorization: Bearer $HEAVEN_API_KEY"
```

```json tab="MCP"
{ "tool": "usage",
  "arguments": { "computer": "my-site" } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "range": "24h",
    "resolution_seconds": 300,
    "series": [
      {},
      {},
      {}
    ],
    "summary": {
      "bucket_start": "2026-11-16T11:00:00Z",
      "computer_id": "3f1c9e2a-7b4d-4c8e-9a6f-2d5b8e1c7a90",
      "covered_seconds": 0,
      "cpu_usec": null,
      "cpu_vcpus_avg": null,
      "cpu_vcpus_max": null,
      "disk_size_bytes": null,
      "disk_used_bytes": null,
      "io_covered_seconds": 0,
      "io_read_bytes": null,
      "io_read_ops": null,
      "io_write_bytes": null,
      "io_write_ops": null,
      "memory_bytes_avg": null,
      "net_covered_seconds": 0,
      "net_rx_bytes": null,
      "net_tx_bytes": null,
      "running": false,
      "vcpus": 0
    }
  }
}
```
