> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravixlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Snapshots

> List named snapshots in the current project

`GET /v1/agents/snapshots`

Returns snapshots in your project. Default list hides snapshots that are being deleted.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from gravixlayer import GravixLayer

  client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
  sandbox = client.runtime.create()  # defaults to template="base-small"

  page = client.snapshots.list(limit=20)
  print(page.total)
  for snap in page.snapshots:
      print(snap.name, snap.kind, snap.state)

  # Filter by kind or source sandbox
  page = client.snapshots.list(kind="hot", runtime_id=sandbox.runtime_id)

  sandbox.kill()
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { GravixLayer } from 'gravixlayer';

  const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
  const sandbox = await client.runtime.create(); // defaults to template="base-small"

  const page = await client.snapshots.list({ limit: 20 });
  console.log(page.total);
  for (const snap of page.snapshots) {
    console.log(snap.name, snap.kind, snap.state);
  }

  // Filter by kind or source sandbox
  const filtered = await client.snapshots.list({ kind: 'hot', runtimeId: sandbox.runtimeId });

  await sandbox.kill();
  ```

  ```bash CLI theme={"theme":{"light":"github-light","dark":"github-dark"}}
  gravixlayer snapshot list
  gravixlayer snapshot list --kind hot --limit 20 --offset 0
  gravixlayer snapshot list --runtime-id "$RT" --output json
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  # Requires: GRAVIXLAYER_API_KEY
  API="https://api.gravixlayer.ai/v1"

  curl -sS "$API/agents/snapshots?limit=20&offset=0" \
    -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

  curl -sS "$API/agents/snapshots?kind=hot&runtime_id=$RT" \
    -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"
  ```
</CodeGroup>

## Query parameters

| Parameter    | Type    | Description                                                  |
| ------------ | ------- | ------------------------------------------------------------ |
| `limit`      | integer | Page size (1–100, default 20)                                |
| `offset`     | integer | Skip this many rows                                          |
| `kind`       | string  | `hot`, `cold`, or `all`                                      |
| `runtime_id` | string  | Only snapshots captured from this sandbox                    |
| `state`      | string  | `active`, `inactive`, `snapshotting`, `error`, or `removing` |

## Response

| Field       | Type    | Description                                                                        |
| ----------- | ------- | ---------------------------------------------------------------------------------- |
| `snapshots` | array   | [Snapshot objects](/documentation/agentruntime/snapshots/overview#snapshot-object) |
| `limit`     | integer | Page size used                                                                     |
| `offset`    | integer | Offset used                                                                        |
| `total`     | integer | Total matching snapshots                                                           |