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

# Capture a snapshot

> Save a machine’s memory and disk as a reusable private snapshot.

## Authentication

Send your scoped bearer token in the `Authorization: Bearer <BEAD_TOKEN>` header, or send your API key in `X-API-Key`.

## Parameters

**id** `string` *required*

Machine identifier returned by creation.

**Idempotency-Key** `string`

Caller-generated durable retry key: lowercase ASCII letters, digits, and hyphens only. Reuse the same key and body after a connection failure. Minimum length: `1`. Maximum length: `255`.

## Request body

The JSON body is required.

**name** `string` (default: snapshot)

Display name for this snapshot.

**inheritCredentials** `boolean` (default: false)

Explicitly consent to copying configured credentials into the snapshot.

**memory** `boolean` (default: true)

Restore retained memory; false is rejected with 501 unsupported\_feature in this deployment.

**retentionSeconds** `integer`

Retention in seconds; omit for no scheduled expiry. Explicit values must be at least 60. Minimum: `60`.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
curl --request POST \
  --url "https://api.bead.run/sandboxes/$SANDBOX_ID/snapshots" \
  --header "X-API-Key: $BEAD_API_KEY" \
  --header 'Idempotency-Key: 48fcb7cf-0f9e-4612-bd37-4c66171c2aae' \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "python-ready",
  "retentionSeconds": 86400
}
JSON
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
# sandbox is returned by Sandbox.create or Sandbox.connect.
snapshot = sandbox.snapshot(name="python-ready", retention_seconds=86400)
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
// sandbox is returned by Sandbox.create or Sandbox.connect.
const snapshot = await sandbox.snapshot({ name: "python-ready", retentionSeconds: 86400 });
```

## Response

### 202

Capture queued; poll GET /snapshots/\{id} until ready.

**snapshotID** `string` *required*

Snapshot identifier to poll or use as a template.

**templateID** `string` *required*

Template identifier for creating machines from this snapshot.

**buildID** `string` *required*

UUID of this immutable snapshot build.

**status** `string` *required*

Capture is queued for publication. Allowed values: `"pending"`.

**name** `string` *required*

Display name supplied for the snapshot.

**names** `string[]` *required*

Names associated with this snapshot.

## Errors

| Status | Meaning |
| - | - |
| 400 | Invalid request values, unsupported bounds, or malformed JSON. |
| 401 | Authentication credential is missing or rejected. |
| 402 | Insufficient prepaid credit (`insufficient_credit`), or snapshot storage billing is unavailable. |
| 403 | The credential lacks the required scope. |
| 404 | The requested resource does not exist or is outside your organization. |
| 409 | Request key reused with a different body (`idempotency_request_mismatch`), or resource ownership/state conflicts. |
| 413 | Request body exceeds the route limit. |
| 429 | Request or resource admission limit exceeded (`admission_limit`; trial capacity can return `free_capacity_full`). Follow limit.next\_action and Retry-After when present. |
| 503 | Service or persistence is temporarily unavailable. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.