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

# Resume a machine

> Resume a paused machine with a funded execution timeout.

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

**autoPause** `boolean` *deprecated*

Automatically pauses the sandbox after the timeout

**memory** `boolean`

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

**timeout** `integer` (default: 15)

Time to live for the sandbox in seconds. Format: `int32`. Minimum: `0`. Maximum: `86400`.

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

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

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

## Response

### 201

The sandbox was resumed successfully.

**alias** `string`

Alias of the template

**clientID** `string` *required* *deprecated*

Identifier of the client

**domain** `string | null`

Base domain where the sandbox traffic is accessible May be `null`.

**envdAccessToken** `string`

Access token used for envd communication

**envdVersion** `string` *required*

Version of the envd running in the sandbox

**grace\_deadline** `string | null`

End of the credit grace period as an RFC 3339 timestamp, or null when funded. May be `null`.

**idle\_timeout** `integer | string | null`

Seconds without activity before a persistent machine pauses, or never to disable idle pause. Persistent machines default to 900 seconds; numeric values must be 300–86400. May be `null`. Accepts `integer` or `string` ("never").

**kind** `string`

Lifetime policy: temporary expires at its timeout; persistent retains state until explicit deletion or the end of credit grace. Allowed values: `"temporary"`, `"persistent"`.

**last\_activity** `string | null`

Most recent activity as an RFC 3339 timestamp, or null when no activity was recorded. May be `null`.

**machine\_state** `string`

Current lifecycle state including running, idle-paused, waking, credit-grace, lost, or deleted. Allowed values: `"running"`, `"idle-paused"`, `"waking"`, `"credit-grace"`, `"lost"`, `"deleted"`.

**paused\_at** `string | null`

Time the machine last paused as an RFC 3339 timestamp, or null when it has not paused. May be `null`.

**sandboxID** `string` *required*

Identifier of the sandbox

**templateID** `string` *required*

Identifier of the template from which is the sandbox created

**trafficAccessToken** `string | null`

Token required for accessing sandbox via proxy. May be `null`.

**wake\_reason** `string | null`

Reason for the last wake or lifecycle transition, or null when none is recorded. May be `null`.

**warnings** `object[]`

Lifecycle or credit grace warnings attached to this machine. Additional keys accept `any` values.

## 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`) for the requested execution window. |
| 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`. |
| 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.