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

# Fork a machine

> Capture a running machine and create ordered children from its memory snapshot.

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

Machine identifier returned by creation.

**Idempotency-Key** `string` *required*

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

**count** `integer` *required*

Number of child machines to create. Minimum: `1`. Maximum: `20`.

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

Funded execution timeout per child in seconds. Minimum: `1`. Maximum: `86400`.

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

Must be false; fork does not inherit credential profiles. Use a consented snapshot to copy them.

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

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

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

## Response

### 202

Fork capture or one or more children are pending.

**operationID** `string` *required*

Fork batch UUID to poll.

**snapshotID** `string` *required*

Snapshot shared by the fork children.

**capture** `object | null` *required*

Memory capture result and source recovery details. May be `null`.

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

**status** `string` *required*

Whether any children are still pending. Allowed values: `"pending"`, `"completed"`.

**results** `object[]` *required*

Ordered child results; a failed child has its own error response.

**Properties**

**index** `integer` *required*

Zero-based request index.

**status** `integer` *required*

HTTP status for this member; 202 means it is still pending.

**operationID** `string`

Operation UUID for a pending member.

**response** `object`

Machine connection fields on success, or an error body on failure. Accepts `object` or `object` or `object`.

**Properties**

**alias** `string`

Alias of the template

**clientID** `string` *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`

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`

Identifier of the sandbox

**templateID** `string`

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.

**code** `integer`

HTTP status code.

**message** `string`

Explanation of the failed request.

**error\_code** `string`

Stable error identifier when supplied; use it to decide how to recover.

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

**operationID** `string`

Operation UUID.

**status** `string`

Current operation state.

### 207

All child attempts finished; inspect each member status.

The response fields are the same as the success body above.

## 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`) to fund the requested machine attempts. |
| 403 | The credential lacks the required scope. |
| 404 | The requested resource does not exist or is outside your organization. |
| 409 | Request key reused with a different body (`idempotency_request_mismatch`), or resource ownership/state conflicts. |
| 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.