# Snapshots (/docs/snapshots)

A snapshot is a capture of the memory and disk of a running sandbox, saved under a name. A sandbox restored from a snapshot resumes the captured processes and memory instead of booting. Deleting the source sandbox does not affect its snapshots.

A Linux sandbox produces a full snapshot, and only a persistent sandbox or one served from a warm template can be captured. A GPU sandbox produces a [checkpoint](/docs/gpu-sandboxes) that also holds GPU memory. A full snapshot restores in its home region, on the runner that captured it or on another runner of the region with the same CPU model and hypervisor version. Where Daytona has enabled cross-region restore, a full snapshot of a sandbox that is not persistent can also restore in another region, which receives a copy of it first. Without it, a restore that names another region returns `400`. A checkpoint restores on any GPU runner in the region that meets the [restore requirements](/docs/gpu-sandboxes). Windows sandboxes do not support snapshots. macOS sandboxes do not produce these snapshots: a macOS filesystem snapshot saves the disk of a stopped persistent sandbox as an image, and it restores on any Mac of the region.

A snapshot holds a running state. To save only the filesystem of a sandbox, [capture an image](/docs/images#capture-images) instead. To register a registry image or a Dockerfile build under a name, [pull](/docs/images#pull-images) or [build](/docs/images#build-images) an image.

<SnapshotVisual />

| **Concept**       | **Description**                                                                                                  |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Full snapshot** | The memory and disk of a running persistent Linux sandbox or one served from a warm template. |
| **Checkpoint**    | The processes, memory, and GPU memory of a running GPU sandbox.                               |
| **Restore**       | A new sandbox that resumes the captured processes and memory, with the CPU, memory, and disk of the source.      |
| **Home region**   | The region of the source sandbox. A snapshot restores there unless the restore names another region.             |
| **Name**          | Unique in the project. Snapshots and images share one name space.                                                |

## Use cases [#use-cases]

Snapshots are used when a new sandbox must continue from a running state instead of booting and repeating its setup.

- **Checkpoints of running work.** A full snapshot saves the memory and disk of a running sandbox. A restore resumes the captured processes instead of starting them again. The capture runs in the background, and the source sandbox keeps running if the capture fails.

- **Fast starts for slow-booting programs.** A full snapshot taken after a server, a kernel, or a model has loaded restores with that program already running. New sandboxes skip the load time. The program must run in a persistent Linux sandbox or one served from a warm template, because only those sandboxes can be captured.

- **Evaluation and reinforcement learning (RL).** Each test case or episode resumes from the same snapshot. Results do not depend on another run. Every restored sandbox keeps the CPU, memory, and disk of the source, so each run gets the same resources.

- **Long GPU jobs.** A checkpoint saves a GPU job together with its GPU memory. A new GPU sandbox resumes the job from the point it was saved. The checkpoint restores on any GPU runner in the region that meets the [restore requirements](/docs/gpu-sandboxes).

- **Parallel attempts from one state.** Several sandboxes restore from the same snapshot, and each continues on its own. An agent tries several approaches from one point without repeating the setup. The snapshot cannot be deleted while a sandbox restored from it exists.

## Create snapshots [#create-snapshots]

Create a snapshot of a running sandbox. The capture runs in the background: the snapshot starts as pending, is building while the runner captures the sandbox, and becomes ready when the capture finishes. Deleting the source sandbox during the capture fails the snapshot.

<Tabs syncKey="language">
<TabItem label="Python" icon="seti:python">

```python
from daytona import Daytona

daytona = Daytona()
# Snapshot capture needs a persistent sandbox or one served from a warm template
sandbox = daytona.v2.create()

snapshot = sandbox.create_snapshot("my-snapshot")
print(snapshot.id, snapshot.kind, snapshot.status)
```

| **Parameter** | **Type** | **Description** |
| ------------- | -------- | --------------- |
| `name` | str | Sets the snapshot name, 1 to 128 characters of letters, digits, `.`, `_`, and `-`. It cannot start with `.` or with the reserved prefixes `sbx_`, `vol_`, `fn_`, `snap-`, `build-`, `refs`, `by-digest`, `prj-`, and `glb-`. Names are case-sensitive. This parameter is required. Snapshots and images in the project share one name space. A name in use fails with `409`. |

The response has the following fields:

| **Field** | **Description** |
| --------- | --------------- |
| `status` | The status is `pending` or `building`, because the call returns before the capture finishes. To wait, call `daytona.v2.snapshots.get(snapshot.id, wait="ready")`. It returns at `ready` or `failed`, or after the server wait of 30 seconds. `timeout` sets a total wait in seconds: the SDK repeats the server wait until the snapshot is `ready` or `failed`, and raises `RequestTimeoutError` if the time runs out first. |

<Callout type="note" title="Notes">
- The request requires the `write:snapshots` permission.
- The sandbox must be running.
- On Linux, the sandbox must be persistent or served from a warm template.
- This call does not support Windows sandboxes.
</Callout>

</TabItem>
<TabItem label="TypeScript" icon="seti:typescript">

```typescript
import { Daytona } from '@daytona/sdk'

const daytona = new Daytona()
// Snapshot capture needs a persistent sandbox or one served from a warm template
const sandbox = await daytona.v2.create()

const snapshot = await sandbox.createSnapshot('my-snapshot')
console.log(snapshot.id, snapshot.kind, snapshot.status)
```

| **Parameter** | **Type** | **Description** |
| ------------- | -------- | --------------- |
| `name` | string | Sets the snapshot name, 1 to 128 characters of letters, digits, `.`, `_`, and `-`. It cannot start with `.` or with the reserved prefixes `sbx_`, `vol_`, `fn_`, `snap-`, `build-`, `refs`, `by-digest`, `prj-`, and `glb-`. Names are case-sensitive. This parameter is required. Snapshots and images in the project share one name space. A name in use fails with `409`. |

The response has the following fields:

| **Field** | **Description** |
| --------- | --------------- |
| `status` | The status is `pending` or `building`, because the call returns before the capture finishes. To wait, call `daytona.v2.snapshots.get(snapshot.id, { wait: 'ready' })`. It returns at `ready` or `failed`, or after the server wait of 30 seconds. `timeoutSeconds` sets a total wait in seconds: the SDK repeats the server wait until the snapshot is `ready` or `failed`, and throws `RequestTimeoutError` if the time runs out first. |

<Callout type="note" title="Notes">
- The request requires the `write:snapshots` permission.
- The sandbox must be running.
- On Linux, the sandbox must be persistent or served from a warm template.
- This call does not support Windows sandboxes.
</Callout>

</TabItem>
<TabItem label="CLI" icon="seti:shell">

```bash
daytona snapshot create {sandboxId} --name my-snapshot
```

| **Flag** | **Type** | **Description** |
| -------- | -------- | --------------- |
| `--name` | string | Sets the snapshot name. This flag is required. |
| `--timeout` | duration | Sets how long the command waits for the snapshot to be `ready`, as a duration such as `30s` or `10m`. The capture continues after the command stops waiting. The default is `10m`. |
| `--no-wait` | boolean | Returns once the capture is queued, without waiting for `ready`. |
| `--file`, `-f` | string | Reads the request body from a JSON file, or from standard input with `-`. Flags override its fields. |

</TabItem>
<TabItem label="API" icon="seti:json">

```bash
curl 'https://api.daytona.com/sandboxes/{sandboxId}/snapshots' \
  --request POST \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "my-snapshot" }'
```

The response has the following fields:

| **Field** | **Description** |
| --------- | --------------- |
| `id` | Identifies the new snapshot. |
| `status` | The status is `pending`. To wait, call `GET /snapshots/{snapshotId}?wait=ready&timeout_ms=60000`. It answers `200` at `ready` or `failed`, or when the wait expires. `timeout_ms` defaults to `30000` and is at most `60000`. |

<Callout type="note" title="Notes">
- The request requires the `write:snapshots` permission.
- The sandbox must be running.
- On Linux, the sandbox must be persistent or served from a warm template.
</Callout>

</TabItem>
</Tabs>

| **Kind**         | **Captures**                                         | **Restore behavior**                                                                                                                                                  |
| ---------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`full`**       | Memory and disk of a Linux sandbox                   | Resumes the captured processes and memory. Requires a persistent sandbox or one served from a warm template. Restores in its home region. A snapshot of a sandbox that is not persistent also restores in a region whose runners have the same CPU model and hypervisor version. |
| **`checkpoint`** | Processes, memory, and GPU memory of a GPU sandbox   | Resumes in a new GPU sandbox. See [GPU sandboxes](/docs/gpu-sandboxes).                                                                                          |

| **Status**      | **Meaning**                                                                                                                                                                 |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending`   | Accepted; the capture job is queued on the sandbox's runner.                                                                                                                |
| `building`  | The runner is pausing, copying, and packing the sandbox state.                                                                                                              |
| `ready`     | Restorable.                                                                                                                                                                 |
| `failed`    | Terminal. `error` carries the reason. The source sandbox keeps running.                                                                                                     |

## Restore snapshots [#restore-snapshots]

Restore a sandbox from a snapshot. It resumes the captured processes and memory and keeps the source sandbox's CPU, memory, disk, and persistence. The restore runs on the runner that captured the snapshot when that runner can take it, and otherwise on another runner of the region with the same CPU model and hypervisor version. Where cross-region restore is enabled, a restore in another region waits while the snapshot is copied there.

<Tabs syncKey="language">
<TabItem label="Python" icon="seti:python">

```python
from daytona import Daytona

daytona = Daytona()

sandbox = daytona.v2.create_from_snapshot("my-snapshot")
```

| **Parameter** | **Type** | **Description** |
| ------------- | -------- | --------------- |
| `snapshot` | str | Sets the snapshot to restore from, by name or by ID, `snap_...`. This parameter is required. |
| `name` | str | Sets the display name. If omitted, a name is generated. |
| `labels` | Dict\[str, str\] | Attaches key-value metadata to the sandbox. |
| `lifecycle_policy` | LifecyclePolicyOptions | Sets the lifecycle policy. It takes the same fields as `lifecycle_policy` in [create a Linux sandbox](/docs/linux-sandboxes#create-a-linux-sandbox). |
| `ports` | Sequence\[PortMapping\] | Forwards inbound ports to the sandbox. Import `PortMapping` from `daytona.v2`, for example `PortMapping(port=8080)`. |
| `region` | str | Sets the region. The default is the snapshot's home region. Another region requires cross-region restore to be enabled, a source sandbox that was not persistent, and runners in that region with the CPU model and hypervisor version of the snapshot. |
| `idempotency_key` | str | Makes a retried create return the same sandbox. If `name` is set, the key is derived from it. Otherwise, each call generates a new key. |
| `wait_seconds` | int | Sets how many seconds create waits for the sandbox to start. The server holds the request for up to 3 seconds, and the SDK waits for the rest. `0` returns immediately. The default is `60`. |
| `create_timeout_seconds` | int | Sets how many seconds the sandbox has to reach running before it is deleted, at most `86400`. `-1` sets the maximum. The default is `3600`. |

<Callout type="note" title="Notes">
- The request requires the `write:sandboxes` permission.
- The snapshot must have the `ready` status.
</Callout>

</TabItem>
<TabItem label="TypeScript" icon="seti:typescript">

```typescript
import { Daytona } from '@daytona/sdk'

const daytona = new Daytona()

const sandbox = await daytona.v2.createFromSnapshot('my-snapshot')
```

| **Parameter** | **Type** | **Description** |
| ------------- | -------- | --------------- |
| `snapshot` | string | Sets the snapshot to restore from, by name or by ID, `snap_...`. This parameter is required. |
| `name` | string | Sets the display name. If omitted, a name is generated. |
| `labels` | Record\<string, string> | Attaches key-value metadata to the sandbox. |
| `lifecyclePolicy` | LifecyclePolicyOptions | Sets the lifecycle policy. It takes the same fields as `lifecyclePolicy` in [create a Linux sandbox](/docs/linux-sandboxes#create-a-linux-sandbox). |
| `ports` | PortMapping\[\] | Forwards inbound ports to the sandbox, for example `[{ port: 8080 }]`. |
| `region` | string | Sets the region. The default is the snapshot's home region. Another region requires cross-region restore to be enabled, a source sandbox that was not persistent, and runners in that region with the CPU model and hypervisor version of the snapshot. |
| `idempotencyKey` | string | Makes a retried create return the same sandbox. If `name` is set, the key is derived from it. Otherwise, each call generates a new key. |
| `waitSeconds` | number | Sets how many seconds create waits for the sandbox to start. The server holds the request for up to 3 seconds, and the SDK waits for the rest. `0` returns immediately. The default is `60`. |
| `createTimeoutSeconds` | number | Sets how many seconds the sandbox has to reach running before it is deleted, at most `86400`. `-1` sets the maximum. The default is `3600`. |

<Callout type="note" title="Notes">
- The request requires the `write:sandboxes` permission.
- The snapshot must have the `ready` status.
</Callout>

</TabItem>
<TabItem label="CLI" icon="seti:shell">

```bash
daytona sandbox create-from-snapshot my-snapshot --name resumed
```

| **Flag** | **Type** | **Description** |
| -------- | -------- | --------------- |
| `--name` | string | Sets the display name. If omitted, a name is generated. |
| `--label` | stringArray | Attaches a label as `KEY=VALUE`. Repeat the flag for each label. |
| `--port` | stringArray | Forwards an inbound port as `PORT` or `PORT/PROTO`. Repeat the flag for each port. |
| `--region` | string | Sets the region. The default is the snapshot's home region. Another region requires cross-region restore to be enabled, a source sandbox that was not persistent, and runners in that region with the CPU model and hypervisor version of the snapshot. |
| `--idempotency-key` | string | Makes a retried create return the same sandbox. The default is a key derived from `--name`, or a random key when no name is set. |
| `--lifecycle-timeout` | duration | Sets the wall-clock lifetime as a Go duration such as `2h`, until `--on-lifecycle-timeout` fires. The default is the project or platform default, if one is enabled. |
| `--on-lifecycle-timeout` | string | Sets the action when `--lifecycle-timeout` elapses. The CLI accepts only `delete`. The default is `pause` when the source sandbox of the snapshot was persistent, and `delete` otherwise. |
| `--idle-timeout` | duration | Sets the idle time as a Go duration, at least `1m`, until `--on-idle-timeout` fires. By default, there is no idle timeout unless the project sets one. |
| `--on-idle-timeout` | string | Sets the action when `--idle-timeout` elapses, `delete`. It is required with `--idle-timeout`. |
| `--create-ttl` | duration | Sets how long the sandbox has to reach running before the server deletes it, as a Go duration. `max` sets the server maximum, 24 hours. The default is `1h`. |
| `--timeout` | duration | Sets how long the command waits for the sandbox to run, as a duration such as `30s` or `10m`. The default is `10m`. |
| `--no-wait` | boolean | Prints the create response once the server answers, without waiting for the sandbox to run. The server holds the response for up to 3 seconds. |
| `--file`, `-f` | string | Reads the request body from a JSON file, or from standard input with `-`. Flags override its fields. |

<Callout type="note" title="Notes">
- The request requires the `write:sandboxes` permission.
- The snapshot must have the `ready` status.
- Reference the snapshot by name or by ID, `snap_...`.
</Callout>

</TabItem>
<TabItem label="API" icon="seti:json">

```bash
curl 'https://api.daytona.com/sandboxes/from-snapshot' \
  --request POST \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "snapshot": "my-snapshot" }'
```

| **Field** | **Type** | **Description** |
| --------- | -------- | --------------- |
| `snapshot` | string | Sets the snapshot to restore from, by name or by ID, `snap_...`. This field is required. |
| `name` | string | Sets the display name. If omitted, a name is generated. |
| `labels` | object | Attaches key-value metadata to the sandbox. |
| `lifecycle_policy` | object | Sets the lifecycle policy. It takes the same fields as `lifecycle_policy` in [create a Linux sandbox](/docs/linux-sandboxes#create-a-linux-sandbox). |
| `ports` | array | Forwards inbound ports to the sandbox. |
| `region_id` | string | Sets the region. The default is the snapshot's home region. Another region requires cross-region restore to be enabled, a source sandbox that was not persistent, and runners in that region with the CPU model and hypervisor version of the snapshot. A region that covers other regions, such as `us-east`, requires `idempotency_key`. |
| `idempotency_key` | string | Makes a retried create return the same sandbox. You can also send it as the `Idempotency-Key` header. |
| `create_timeout_seconds` | integer | Sets how many seconds the sandbox has to reach running before it is deleted, at most `86400`. `-1` sets the maximum. The default is `3600`. |
| `wait_seconds` | integer | Sets how many seconds the server holds the request for the sandbox to start, at most `3`. `0` returns immediately. The default is `3`. |

<Callout type="note" title="Notes">
- The request requires the `write:sandboxes` permission.
- The snapshot must have the `ready` status.
</Callout>

</TabItem>
</Tabs>

## Operations [#operations]

### List snapshots [#list-snapshots]

<Tabs syncKey="language">
<TabItem label="Python" icon="seti:python">

```python
from daytona import Daytona

daytona = Daytona()

page = daytona.v2.snapshots.list()
for snapshot in page.items:
    print(snapshot.name, snapshot.kind, snapshot.status)
```

| **Parameter** | **Type** | **Description** |
| ------------- | -------- | --------------- |
| `name` | str | Filters the list by exact snapshot name. |
| `sandbox_id` | str | Filters the list to snapshots captured from this sandbox. |
| `limit` | int | Sets the page size, from `1` to `200`. The default is `100`. |
| `cursor` | str | Resumes the list after the previous page. Pass the `next_cursor` of that page. |

</TabItem>
<TabItem label="TypeScript" icon="seti:typescript">

```typescript
import { Daytona } from '@daytona/sdk'

const daytona = new Daytona()

const page = await daytona.v2.snapshots.list()
for (const snapshot of page.items) {
  console.log(snapshot.name, snapshot.kind, snapshot.status)
}
```

| **Parameter** | **Type** | **Description** |
| ------------- | -------- | --------------- |
| `name` | string | Filters the list by exact snapshot name. |
| `sandboxId` | string | Filters the list to snapshots captured from this sandbox. |
| `limit` | number | Sets the page size, from `1` to `200`. The default is `100`. |
| `cursor` | string | Resumes the list after the previous page. Pass the `nextCursor` of that page. |

</TabItem>
<TabItem label="CLI" icon="seti:shell">

```bash
daytona snapshot list
```

| **Flag** | **Type** | **Description** |
| -------- | -------- | --------------- |
| `--limit` | int | Sets the page size, from `1` to `200`. The default is `100`. |
| `--cursor` | string | Resumes the list after the previous page. |

</TabItem>
<TabItem label="API" icon="seti:json">

```bash
curl 'https://api.daytona.com/snapshots' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

| **Field** | **Type** | **Description** |
| --------- | -------- | --------------- |
| `name` | string | Filters the list by exact snapshot name. |
| `sandbox_id` | string | Filters the list to snapshots captured from this sandbox. |
| `limit` | integer | Sets the page size, from `1` to `200`. The default is `100`. |
| `cursor` | string | Resumes the list after the previous page. Pass the `next_cursor` of that page. |

</TabItem>
</Tabs>

The API returns the following fields. The SDKs use the same names, except where the description says otherwise.

| **Field**          | **Description**                                                                                                                            |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`           | Snapshot ID.                                                                                                                               |
| `name`         | Unique name within the project. Used for restore.                                                                                          |
| `class`        | `linux` or `gpu`. The SDKs name it `sandbox_class` in Python and `sandboxClass` in TypeScript.                                         |
| `kind`         | `full` for Linux, or `checkpoint` for GPU.                                                                                             |
| `status`       | `pending`, `building`, `ready`, or `failed`.                                                                                               |
| `sandbox_id`   | The ID of the source sandbox. It stays after the source sandbox is deleted, and becomes `null` once Daytona purges the record of the deleted sandbox. |
| `region_id`    | Home region. The SDKs name it `region`.                                                                                                    |
| `region_ids`   | The home region, followed by every other region that holds a copy of the snapshot. The SDKs name it `available_in` in Python and `availableIn` in TypeScript. |
| `bytes`        | Size of the captured disk in bytes. `null` for `full` snapshots.                                                                           |
| `memory_bytes` | Size of the captured memory, `full` only.                                                                                                  |
| `error`        | Failure reason when `status` is `failed`.                                                                                                  |

#### Iterate over all snapshots [#iterate-over-all-snapshots]

<Tabs syncKey="language">
<TabItem label="Python" icon="seti:python">

```python
from daytona import Daytona

daytona = Daytona()

for snapshot in daytona.v2.snapshots.iter():
    print(snapshot.name, snapshot.kind, snapshot.status)
```

</TabItem>
<TabItem label="TypeScript" icon="seti:typescript">

```typescript
import { Daytona } from '@daytona/sdk'

const daytona = new Daytona()

for await (const snapshot of daytona.v2.snapshots.iter()) {
  console.log(snapshot.name, snapshot.kind, snapshot.status)
}
```

</TabItem>
<TabItem label="CLI" icon="seti:shell">

```bash
# Follow every page until the server returns no cursor
daytona snapshot list --all
```

</TabItem>
<TabItem label="API" icon="seti:json">

```bash
curl 'https://api.daytona.com/snapshots?cursor={next_cursor}' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

</TabItem>
</Tabs>

### Get a snapshot [#get-a-snapshot]

<Tabs syncKey="language">
<TabItem label="Python" icon="seti:python">

```python
from daytona import Daytona

daytona = Daytona()

snapshot = daytona.v2.snapshots.get("{snapshotId}")
print(snapshot.kind, snapshot.status)
```

<Callout type="note" title="Notes">
- The request requires the `read:snapshots` permission.
- `get` takes the snapshot ID, `snap_...`, or the name.
</Callout>

</TabItem>
<TabItem label="TypeScript" icon="seti:typescript">

```typescript
import { Daytona } from '@daytona/sdk'

const daytona = new Daytona()

const snapshot = await daytona.v2.snapshots.get('{snapshotId}')
console.log(snapshot.kind, snapshot.status)
```

<Callout type="note" title="Notes">
- The request requires the `read:snapshots` permission.
- `get` takes the snapshot ID, `snap_...`, or the name.
</Callout>

</TabItem>
<TabItem label="CLI" icon="seti:shell">

```bash
daytona snapshot get {snapshotId}
```

<Callout type="note" title="Notes">
- The request requires the `read:snapshots` permission.
- The command takes the snapshot ID, `snap_...`, or the name.
</Callout>

</TabItem>
<TabItem label="API" icon="seti:json">

```bash
curl 'https://api.daytona.com/snapshots/{snapshotId}' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

| **Field** | **Type** | **Description** |
| --------- | -------- | --------------- |
| `id_only` | boolean | Resolves the path value only as an ID, without falling back to a name. The default is `false`. |

<Callout type="note" title="Notes">
- The request requires the `read:snapshots` permission.
- The path takes the snapshot ID, `snap_...`, or the name.
</Callout>

</TabItem>
</Tabs>

### Delete snapshots [#delete-snapshots]

Delete a snapshot. It cannot be deleted while a sandbox restored from it exists, including a restored sandbox whose deletion has not finished.

1. Go to [Daytona Dashboard ↗](https://app.daytona.com/dashboard/snapshots)
2. Open the actions menu of a snapshot and click <Button>Delete</Button>
3. Click <Button>Delete</Button> to confirm

<Tabs syncKey="language">
<TabItem label="Python" icon="seti:python">

```python
from daytona import Daytona

daytona = Daytona()

daytona.v2.snapshots.delete("{snapshotId}")
```

</TabItem>
<TabItem label="TypeScript" icon="seti:typescript">

```typescript
import { Daytona } from '@daytona/sdk'

const daytona = new Daytona()

await daytona.v2.snapshots.delete('{snapshotId}')
```

</TabItem>
<TabItem label="CLI" icon="seti:shell">

```bash
daytona snapshot delete {snapshotId}
```

<Callout type="note" title="Notes">
- The request requires the `delete:snapshots` permission.
- The command asks for confirmation.
- A non-interactive shell requires `--yes`.
</Callout>

</TabItem>
<TabItem label="API" icon="seti:json">

```bash
curl 'https://api.daytona.com/snapshots/{snapshotId}' \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

| **Field** | **Type** | **Description** |
| --------- | -------- | --------------- |
| `id_only` | boolean | Resolves the path value only as an ID, without falling back to a name. The default is `false`. |

</TabItem>
</Tabs>

## Errors [#errors]

The SDKs raise these errors with the codes in the following table, and the API returns them in the `code` field.

| **Code**                       | **Meaning**                                                                                                                                                                                                                              | **What to do**                                                                                                   |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **`SNAPSHOT_NOT_FOUND`**       | The restore names a snapshot that does not exist in the project.                                                                                                                                                                         | Check the name or ID with [list snapshots](#list-snapshots).                                                     |
| **`SNAPSHOT_NOT_READY`**       | The restore names a snapshot that is `pending`, `building`, or `failed`.                                                                                                                                                                 | Wait until the snapshot is `ready`. A `failed` snapshot does not become `ready`: create a new one.               |
| **`NOT_SUPPORTED_FOR_CLASS`**  | The snapshot create names a Windows or macOS sandbox.                                                                                                                                                                                          | To save the disk, [capture an image](/docs/images#capture-images).                                               |
| **`IDEMPOTENCY_KEY_REQUIRED`** | An API restore names a region that covers other regions, such as `us-east`, without an `Idempotency-Key` header. The SDKs and the CLI always send a key.                                                                                  | Pass an idempotency key, or name a single region.                                                                |
| **`CONFLICT`**                 | The name is in use by a snapshot or an image, the sandbox is not running, the Linux sandbox is neither persistent nor served from a warm template, the target region has no runner with the CPU model and hypervisor version of the snapshot, or a delete names a snapshot that a sandbox still references. | Use another name, start the sandbox, restore in the home region, or delete the restored sandboxes first.        |
| **`BAD_REQUEST`**              | The snapshot name is invalid, the restore names another region that the snapshot cannot be copied to (for example, cross-region restore is not enabled, the source sandbox was persistent, or the snapshot is too large), the restore names a `checkpoint`, or the path value matches both a snapshot ID and the name of another snapshot. | Fix the name, restore in the home region, restore a `checkpoint` as a [GPU sandbox](/docs/gpu-sandboxes), or pass `id_only`. |

## Permissions [#permissions]

Snapshots are scoped to a project. Access is governed by three permissions, which you can grant to an [organization role](/docs/organizations#roles) or an [API key](/docs/api-keys).

Restoring a snapshot creates a sandbox, so it requires the permission to create sandboxes. The [audit logs](/docs/audit-logs) record snapshot creates and deletes.

| **Permission**         | **Grants**             |
| ---------------------- | ---------------------- |
| **`read:snapshots`**   | List and get snapshots |
| **`write:snapshots`**  | Create snapshots       |
| **`delete:snapshots`** | Delete snapshots       |