Resume a machine

POST

sandboxes

{sandboxID}

resume

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

# sandbox is returned by Sandbox.create or Sandbox.connect.
sandbox.resume(timeout=300)

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

{
  "alias": "<string>",
  "clientID": "<string>",
  "domain": {},
  "envdAccessToken": "<string>",
  "envdVersion": "<string>",
  "grace_deadline": {},
  "idle_timeout": {},
  "kind": "<string>",
  "last_activity": {},
  "machine_state": "<string>",
  "paused_at": {},
  "sandboxID": "<string>",
  "templateID": "<string>",
  "trafficAccessToken": {},
  "wake_reason": {},
  "warnings": [
    {}
  ]
}

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

deprecated

Automatically pauses the sandbox after the timeout

boolean

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

integer

default:15

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

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

# sandbox is returned by Sandbox.create or Sandbox.connect.
sandbox.resume(timeout=300)

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

Response

201

The sandbox was resumed successfully.

string

Alias of the template

string

required

deprecated

Identifier of the client

string | null

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

string

Access token used for envd communication

string

required

Version of the envd running in the sandbox

string | null

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

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”).

string

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

string | null

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

string

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

string | null

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

string

required

Identifier of the sandbox

string

required

Identifier of the template from which is the sandbox created

string | null

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

string | null

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

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.

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

# sandbox is returned by Sandbox.create or Sandbox.connect.
sandbox.resume(timeout=300)

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

{
  "alias": "<string>",
  "clientID": "<string>",
  "domain": {},
  "envdAccessToken": "<string>",
  "envdVersion": "<string>",
  "grace_deadline": {},
  "idle_timeout": {},
  "kind": "<string>",
  "last_activity": {},
  "machine_state": "<string>",
  "paused_at": {},
  "sandboxID": "<string>",
  "templateID": "<string>",
  "trafficAccessToken": {},
  "wake_reason": {},
  "warnings": [
    {}
  ]
}

Start here

Endpoints

Resume a machine

Authentication

Parameters

Request body

Response

201

Errors

​Authentication

​Parameters

​Request body

​Response

​201

​Errors

Authentication

Parameters

Request body

Response

201

Errors