# List or read snapshots

URL: https://heaven.dev/docs/reference/snapshots/view
Updated: 2026-11-21

List Computer snapshots or read one snapshot's details. Use the snapshot's name or ID to restore its disk or make a copy.

`GET /v1/computer/snapshot/`

## Parameters

- `computer` (string): Computer name or ID. Omit to list snapshots across your Computers.
- `snapshot` (string): Snapshot name or ID within the named Computer.
- `sort` (string): Order for a snapshot list. Give size for largest first. Omit for newest first.
- `limit` (string): Maximum snapshots per page. MCP defaults to 100. Use the returned next value with `after` for more matches.
- `after` (string): Snapshot ID to list after in the current sort order. Use the previous page's next value.

## Returns

- `data` (object, always present): Snapshots and their storage measurements, or one named snapshot.
  - `alternative-1` (object): Visible snapshots and their latest storage measurements.
    - `computers` (object[] | null, always present): Storage that deleting each Computer's snapshots would free: on a page, the Computers of its snapshots.
      - `items` (object): Storage recoverable by deleting a Computer's snapshots together.
        - `id` (string, always present): Computer ID.
        - `name` (string, always present): Computer name.
        - `snapshot_bytes` (string | null, always present): Bytes freed by deleting all this Computer's snapshots, as a decimal string; null if unknown.
    - `next` (string): The `after` of the next page. Absent on the last page. May be omitted.
    - `observed_at` (string (date-time) | null, always present): Time of the storage observation, or null when unknown.
    - `pools` (object[] | null, always present): Storage use in the pools you can read.
      - `items` (object): A pool's included and used storage. Byte counts are decimal strings; null measurements are unknown.
        - `allowance_bytes` (string | null, always present): Included storage for files and snapshots, in bytes.
        - `files_bytes` (string | null, always present): Storage used by files, in bytes.
        - `id` (string, always present): Pool ID.
        - `snapshot_bytes` (string | null, always present): Storage used by snapshots, in bytes.
        - `used_bytes` (string | null, always present): Files and snapshots together, in bytes.
    - `snapshots` (object[] | null, always present): Snapshots matching the request.
      - `items` (object): A point-in-time disk snapshot. Byte counts are decimal strings; null measurements are unknown.
        - `automatic` (boolean, always present): Whether Heaven created the snapshot automatically.
        - `changed_since_bytes` (string | null, always present): Bytes changed since this snapshot.
        - `computer` (object, always present): Computer whose disk was snapshotted.
          - `id` (string, always present): Referenced object's stable ID.
          - `name` (string, always present): Referenced object's name.
        - `copies` (object[] | null, always present): Accessible Computers originating from this snapshot, including those later reset or restored.
          - `items` (object): A Computer, pool or snapshot reference.
            - `id` (string, always present): Referenced object's stable ID.
            - `name` (string, always present): Referenced object's name.
        - `created_by` (object, always present): Who requested the snapshot.
          - `email` (string | null, always present): Their email address, or null when none is available.
          - `user_id` (string, always present): Person's user ID.
        - `data_bytes` (string | null, always present): Reported snapshot data, in bytes.
        - `data_source` (string | null, always present): Where the data-size measurement came from.
        - `disk_bytes` (string | null, always present): Logical disk size at capture, in bytes.
        - `expires_at` (string (date-time) | null, always present): When the snapshot expires. Null keeps it until explicitly deleted.
        - `id` (string, always present): Snapshot ID.
        - `kept_by` (object[] | null, always present): Snapshots retaining this deleted snapshot. Null unless dependencies delay deletion.
          - `items` (object): A Computer, pool or snapshot reference.
            - `id` (string, always present): Referenced object's stable ID.
            - `name` (string, always present): Referenced object's name.
        - `kept_by_computers` (object[] | null, always present): Accessible copied Computers whose disks still retain this deleted snapshot's data.
          - `items` (object): A Computer, pool or snapshot reference.
            - `id` (string, always present): Referenced object's stable ID.
            - `name` (string, always present): Referenced object's name.
        - `kept_by_other_copies` (integer): Number of copied Computers you cannot access that retain this snapshot. May be omitted.
        - `name` (string, always present): Snapshot's name within its Computer.
        - `note` (string, always present): Saved note about this snapshot.
        - `observed_at` (string (date-time) | null, always present): Time the measurements were last reported.
        - `requested_at` (string (date-time), always present): When snapshot creation was requested.
        - `saved` (string | null, always present): Disk capture method: `stopped`, `flushed` or `unflushed`. Flushing does not guarantee application consistency. Null means capture is unreported.
        - `size_bytes` (string | null, always present): Storage unique to this snapshot, in bytes.
        - `state` (string, always present): Snapshot lifecycle state. `pending` awaits disk capture.
        - `taken_at` (string (date-time) | null, always present): When the disk snapshot was taken, or null before it has been reported.
    - `stale` (boolean, always present): Whether the measurements are too old to treat as current.
    - `total` (integer, always present): How many snapshots the list holds, on every page.
  - `alternative-2` (object): The selected snapshot.
    - `snapshot` (object, always present): Selected snapshot.
      - `automatic` (boolean, always present): Whether Heaven created the snapshot automatically.
      - `changed_since_bytes` (string | null, always present): Bytes changed since this snapshot.
      - `computer` (object, always present): Computer whose disk was snapshotted.
        - `id` (string, always present): Referenced object's stable ID.
        - `name` (string, always present): Referenced object's name.
      - `copies` (object[] | null, always present): Accessible Computers originating from this snapshot, including those later reset or restored.
        - `items` (object): A Computer, pool or snapshot reference.
          - `id` (string, always present): Referenced object's stable ID.
          - `name` (string, always present): Referenced object's name.
      - `created_by` (object, always present): Who requested the snapshot.
        - `email` (string | null, always present): Their email address, or null when none is available.
        - `user_id` (string, always present): Person's user ID.
      - `data_bytes` (string | null, always present): Reported snapshot data, in bytes.
      - `data_source` (string | null, always present): Where the data-size measurement came from.
      - `disk_bytes` (string | null, always present): Logical disk size at capture, in bytes.
      - `expires_at` (string (date-time) | null, always present): When the snapshot expires. Null keeps it until explicitly deleted.
      - `id` (string, always present): Snapshot ID.
      - `kept_by` (object[] | null, always present): Snapshots retaining this deleted snapshot. Null unless dependencies delay deletion.
        - `items` (object): A Computer, pool or snapshot reference.
          - `id` (string, always present): Referenced object's stable ID.
          - `name` (string, always present): Referenced object's name.
      - `kept_by_computers` (object[] | null, always present): Accessible copied Computers whose disks still retain this deleted snapshot's data.
        - `items` (object): A Computer, pool or snapshot reference.
          - `id` (string, always present): Referenced object's stable ID.
          - `name` (string, always present): Referenced object's name.
      - `kept_by_other_copies` (integer): Number of copied Computers you cannot access that retain this snapshot. May be omitted.
      - `name` (string, always present): Snapshot's name within its Computer.
      - `note` (string, always present): Saved note about this snapshot.
      - `observed_at` (string (date-time) | null, always present): Time the measurements were last reported.
      - `requested_at` (string (date-time), always present): When snapshot creation was requested.
      - `saved` (string | null, always present): Disk capture method: `stopped`, `flushed` or `unflushed`. Flushing does not guarantee application consistency. Null means capture is unreported.
      - `size_bytes` (string | null, always present): Storage unique to this snapshot, in bytes.
      - `state` (string, always present): Snapshot lifecycle state. `pending` awaits disk capture.
      - `taken_at` (string (date-time) | null, always present): When the disk snapshot was taken, or null before it has been reported.

## 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: `snapshot view`.

## Examples

```sh tab="heaven CLI"
heaven snapshot view [COMPUTER] [SNAPSHOT]
  [--sort SORT]
  [--limit N]
  [--after AFTER]
```

```sh tab="SSH"
ssh cli@heaven.dev snapshot view [COMPUTER] [SNAPSHOT]
  [--sort SORT]
  [--limit N]
  [--after AFTER]
```

```sh tab="cURL"
curl https://heaven.dev/v1/computer/snapshot/ \
  -H "Authorization: Bearer $HEAVEN_API_KEY"
```

```json tab="MCP"
{ "tool": "snapshot_view",
  "arguments": {  } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "computers": [
      {
        "id": "8a2d6f4b-1e3c-4b7a-8d9e-5c0f3a6b2e14",
        "name": "my-api",
        "snapshot_bytes": null
      },
      {
        "id": "3f1c9e2a-7b4d-4c8e-9a6f-2d5b8e1c7a90",
        "name": "my-site",
        "snapshot_bytes": null
      }
    ],
    "observed_at": null,
    "pools": [
      {
        "allowance_bytes": null,
        "files_bytes": null,
        "id": "pool-e4a666a616f8a550",
        "snapshot_bytes": null,
        "used_bytes": null
      }
    ],
    "snapshots": [],
    "stale": true,
    "total": 0
  }
}
```
