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

# Pause a machine

> Pause a machine while retaining its memory and disk for a later resume.

## Authentication

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

## Parameters

**sandboxID** `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 optional.

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

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

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

The pause checks that the sandbox guest agent answers before it takes the snapshot. By default an unresponsive agent is recorded on the snapshot and the pause proceeds; the sandbox then shows `envdUnresponsiveAtPause` and a later resume must ask for `memory: false`, since restoring that memory would bring the unresponsive agent back. With this true, the pause is instead refused with 503 while the agent does not answer, and the sandbox keeps running. A filesystem-only pause (`memory: false`) is always refused while the agent does not answer, whatever this says.

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

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

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
// sandbox is returned by Sandbox.create or Sandbox.connect.
await sandbox.pause();
```

## Response

### 204

The sandbox was paused successfully and can be resumed.

No response body.

## Errors

| Status | Meaning |
| - | - |
| 400 | Invalid request values, unsupported bounds, or malformed JSON. |
| 401 | Authentication credential is missing or rejected. |
| 403 | The credential lacks the required scope. |
| 404 | The requested resource does not exist or is outside your organization. |
| 409 | Ownership/state conflict or request is already active (`idempotency_in_progress`, `idempotency_request_mismatch`). An expired execution attempt returns `execution_expired`. Activity changed before pause completed (`activity_race`); inspect current machine state. |
| 410 | Execution memory was lost (`machine_lost`); create a new machine or explicitly recover a checkpoint. |
| 413 | Request body exceeds the route limit. |
| 422 | The prior operation outcome is unknown (`idempotency_outcome_unknown`), or the JSON body does not match the request contract. |
| 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. |
| 500 | Machine operation failed (`execution_failed`), or a capture was preserved for recovery (`snapshot_preserved`). Inspect the machine before issuing another operation. |
| 501 | This request selects a feature this deployment does not support (`unsupported_feature`). |
| 503 | Service or persistence is temporarily unavailable. |
| 504 | Machine acknowledgement deadline exceeded; inspect state before retrying the same request key. |


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