---
title: "Snapshot a running or paused sandbox, to start new sandboxes from."
method: POST
path: "/v1/sandboxes/{id}:snapshot"
tags: ["snapshots"]
---

# Snapshot a running or paused sandbox, to start new sandboxes from.

`POST /v1/sandboxes/{id}:snapshot`

## Request

- Base URL: `https://api.withruntime.com`
- URL: `https://api.withruntime.com/v1/sandboxes/{id}:snapshot`
- Auth: HTTP bearer

A running sandbox is paused for the moment it takes to capture, then woken again, as a fork's source is; the answer comes once the capture is over (up to a minute; one still capturing then leaves the sandbox paused until it is ready, so wake it after). A paused one stays paused; send Prefer: wait=10 to wait for its snapshot to be ready. Start copies with POST /v1/sandboxes and snapshot: <id>. Memory snapshots (the default) continue the saved machine: same files, same running processes, same memory, its own clock and a freshly seeded random number generator. A process that seeded its own generator before the snapshot keeps that seed in every copy. With mode: disk, only files are saved and each copy boots afresh without the old processes. A snapshot keeps the saved state used to start new sandboxes. Retained snapshots are copied off the host after any pending memory compression finishes, encrypted under your organization's own key; backedUp is true once that copy is checked. If the host is lost, the snapshot is restored onto another host from that copy and forks run there (they answer snapshot_restoring meanwhile). Only the root disk is kept, so a sandbox with volumes cannot be snapshotted.

## Path parameters

- `id` string, required: Resource identifier (UUID).

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `name` string: Your own handle for the resource. Letters, digits, dot, dash, underscore.
  - `labels` object: Your own key/value tags, at most 32. Filter lists with label=key:value.
  - `retentionDays` integer: Days to keep it, 1 to 365, never past a year from when it was taken. Omit it to keep the snapshot while your account has credit, up to a year from when it was taken (seven days without credit).
  - `mode` 'memory' | 'disk': memory (default) saves the whole machine; disk saves files for a fresh boot, without old processes.

## Response `200`

Success

- object
  - `id` string, required
  - `kind` 'snapshot', required
  - `mode` 'memory' | 'disk'
  - `status` string, required
  - `state` 'capturing' | 'ready' | 'failed' | 'deleting' | 'deleted', required
  - `name` string, nullable
  - `sourceSandboxId` string, required
  - `placement` string, nullable: Opaque tag of the server it is kept on, as a sandbox's placement: its copies start there, or on a server holding a checked copy of it. Keep sources on separate servers with spreadFrom on create.
  - `shape` object, required
    - `vcpu` integer
    - `memoryMiB` integer
    - `diskMiB` integer
    - `memoryGuarantee` string
  - `retentionDays` integer, nullable: Days it is kept, or null: kept while your account has credit, up to a year from when it was taken.
  - `compressionPending` boolean: True while raw fork memory awaits verified compression. Ready snapshots remain startable on their current host. This workspace is unbilled and has no off-host copy until final publication; cross-host copies wait for compression.
  - `storedBytes` integer, nullable
  - `meteredBytes` integer, nullable: What storage is metered for: the final bytes this snapshot alone stores. Zero while compressionPending is true.
  - `backedUp` boolean: Whether its copy off the host is made and checked.
  - `durability` object
    - `state` 'none' | 'pending' | 'durable' | 'failed' | 'restoring': none: no off-host copy yet, including a temporary fork snapshot or pending memory compression. pending: being copied. durable: copied and checked. restoring: its host was lost and it is being restored onto another. failed: it could not be copied.
    - `durableAt` string, nullable
    - `storedBytes` integer, nullable: What the copy off the host stores, compressed and encrypted.
  - `error` string, nullable
  - `createdAt` string
  - `readyAt` string, nullable
  - `expiresAt` string, nullable, required: When it is deleted. Null while it is kept as long as your account has credit.

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/withruntime/apis/runtime-cloud-api.md) · [All operations](https://skmtc.dev/withruntime/apis/runtime-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/withruntime/apis/runtime-cloud-api/revisions/6f4012286988?raw)