> ## 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.

# Set snapshot retention

> Change a snapshot’s retention period or clear its scheduled expiry.

## 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*

Snapshot template identifier returned by capture.

## Request body

The JSON body is required.

**retentionSeconds** `integer | null`

Retention from now in seconds; null or omission clears scheduled expiry. Minimum: `60`. May be `null`.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
curl --request POST \
  --url "https://api.bead.run/snapshots/$SNAPSHOT_ID/extend" \
  --header "X-API-Key: $BEAD_API_KEY" \
  --header "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "retentionSeconds": 86400
}
JSON
```

## Response

### 200

Snapshot publication and storage status.

**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*

Publication state; retired snapshots cannot create new machines.

**name** `string` *required*

Display name supplied for the snapshot.

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

Names associated with this snapshot.

**memoryRestored** `boolean` *required*

Whether capture has reached the ready state.

**error** `string | null` *required*

Capture failure message, or null when no failure is recorded. May be `null`.

**remoteCopyStatus** `string` *required*

Status of the remote snapshot copy: ready, pending, or unavailable.

**sourceStatus** `string` *required*

Current state of the source machine, including preserved when recovery is required.

**sourceBilling** `string` *required*

Who funds the source machine: tenant, platform, or none.

**sourceSandbox** `string | null` *required*

Identifier of the machine captured by this snapshot. May be `null`.

**storageBoundBytes** `integer | null` *required*

Maximum retained storage bytes authorized for this snapshot. May be `null`.

**storageChargedUnits** `integer` *required*

Credit units debited for retained snapshot storage.

**retainUntilMs** `integer | null` *required*

Deletion deadline in Unix milliseconds; null means no scheduled expiry. May be `null`.

**expiryWarningSeconds** `integer` *required*

Seconds before scheduled expiry when a warning is issued.

**storedBytes** `integer | null` *required*

Most recent confirmed physical storage byte count. May be `null`.

**monthlyStorageUsd** `number | null` *required*

Estimated monthly storage charge for the confirmed bytes. May be `null`.

**graceDeadlineMs** `integer | null` *required*

End of storage credit grace in Unix milliseconds, or null when funded. May be `null`.

**graceState** `string` *required*

Storage funding state: funded, credit-grace, or deleted.

**preserved** `boolean`

Whether the source machine is preserved for recovery.

**retryable** `boolean`

Whether you can retry this failed capture.

**nextAction** `string`

Recommended source or snapshot recovery action.

**error\_code** `string`

Machine-readable capture error, such as admission\_limit.

**warnings** `object[]` *required*

Storage grace and expiry warnings.

**limit** `object`

The resource limit that blocked the request.

**Properties**

**limit** `string` *required*

Name of the exhausted resource.

**maximum** `integer` *required*

Allowed amount of this resource.

**usage** `integer` *required*

Current usage counted against the limit.

**next\_action** `string` *required*

Action you can take to proceed.

**reset\_at** `integer`

Unix time in seconds when this time window resets.

**capture** `object`

Memory capture result and source recovery details.

**Properties**

**sourcePreserved** `boolean` *required*

Whether the source was preserved for recovery.

**sourceBilling** `string` *required*

Who pays for the source after capture. Allowed values: `"platform"`, `"tenant"`.

**capturedAtMs** `integer` *required*

Capture timestamp in Unix milliseconds.

**freezeNanos** `integer` *required*

Source freeze duration in nanoseconds.

**sourceResumed** `boolean` *required*

Whether the source resumed after capture.

**timing** `object` *required*

Time spent in each capture stage.

**Properties**

**incremental** `boolean` *required*

Whether this capture used an incremental memory dump.

**dirtyMemoryBytes** `integer` *required*

Allocated memory dump bytes before flattening.

**totalNanos** `integer` *required*

Total capture time in nanoseconds.

**pauseNanos** `integer` *required*

Pause time in nanoseconds.

**dumpNanos** `integer` *required*

Memory dump time in nanoseconds.

**diskReflinkNanos** `integer` *required*

Disk clone time in nanoseconds.

**adoptNanos** `integer` *required*

Snapshot adoption time in nanoseconds.

**cleanupNanos** `integer` *required*

Cleanup time in nanoseconds.

**resumeNanos** `integer` *required*

Source resume time in nanoseconds.

**publicationNanos** `integer` *required*

Publication time in nanoseconds.

## Errors

| Status | Meaning |
| - | - |
| 400 | Invalid request values, unsupported bounds, or malformed JSON. |
| 401 | Authentication credential is missing or rejected. |
| 402 | Retained snapshot storage cannot be funded (`insufficient_credit` when prepaid balance is too low). |
| 403 | The credential lacks the required scope. |
| 404 | The requested resource does not exist or is outside your organization. |
| 409 | The snapshot storage state conflicts with the retention change. |
| 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.