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

# Sandbox snapshot retention

> Manage sandbox snapshot retention by setting or clearing expiry, extending deadlines, and retiring saved snapshots.

Sandbox snapshot retention has no scheduled auto-delete by default, but storage must remain funded. You can set an explicit expiry, change it, or clear it.

## Read retention state

```bash theme={null}
bead sandbox snapshot get SNAPSHOT_ID
```

Inspect `retainUntilMs`, `storedBytes`, `monthlyStorageUsd`, `graceState`, `graceDeadlineMs`, and warnings. A null `retainUntilMs` means there is no scheduled expiry.

## Set an expiry

The create API accepts `retentionSeconds` with a minimum of 60 seconds and no 24-hour maximum:

```json theme={null}
{"name":"prepared","retentionSeconds":86400}
```

To change an existing snapshot's retention, save this as `retention.json`:

```json theme={null}
{"retentionSeconds":172800}
```

```bash theme={null}
bead api POST /snapshots/SNAPSHOT_ID/extend --input retention.json
```

Read the resulting deadline from snapshot detail. Save `{}` as `retention.json` and submit it to the same endpoint to clear scheduled expiry; `null` is also accepted for `retentionSeconds`.

## Keep storage funded

Retained snapshot storage is metered by unique retained bytes and funded through [prepaid credit](https://docs.bead.run/platform/prepaid-credit.md). Run `bead pricing` or call `GET /v1/pricing` for current rates.

Storage funding uses credit grace and deadline warnings. Add credit before the reported grace deadline. Clearing an optional expiry does not remove the funding requirement.

## Retire a snapshot

```bash theme={null}
bead api DELETE /snapshots/SNAPSHOT_ID
```

Retirement prevents new creates from that snapshot. Existing machines retain their own references. Do not use retirement as a way to change the contents of an immutable version; capture a new snapshot instead.

See [snapshot creation](https://docs.bead.run/snapshots/overview.md) and [persistent volumes](https://docs.bead.run/platform/volumes.md) for their separate retention rules.


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