Pause a machine

POST

sandboxes

{sandboxID}

pause

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

# sandbox is returned by Sandbox.create or Sandbox.connect.
sandbox.pause()

// sandbox is returned by Sandbox.create or Sandbox.connect.
await sandbox.pause();

Authentication

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

Parameters

string

required

Machine identifier returned by creation.

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.

boolean

default:true

Restore retained memory; false is rejected with 501 unsupported_feature in this deployment.

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.

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

# sandbox is returned by Sandbox.create or Sandbox.connect.
sandbox.pause()

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

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

# sandbox is returned by Sandbox.create or Sandbox.connect.
sandbox.pause()

// sandbox is returned by Sandbox.create or Sandbox.connect.
await sandbox.pause();

Start here

Endpoints

Pause a machine

Authentication

Parameters

Request body

Response

204

Errors

​Authentication

​Parameters

​Request body

​Response

​204

​Errors

Authentication

Parameters

Request body

Response

204

Errors