List machines

GET

sandboxes

curl --request GET \
  --url "https://api.bead.run/v2/sandboxes" \
  --header "X-API-Key: $BEAD_API_KEY"

{
  "response": [
    {
      "alias": "<string>",
      "clientID": "<string>",
      "cpuCount": 123,
      "diskSizeMB": 123,
      "endAt": {},
      "envdUnresponsiveAtPause": true,
      "envdVersion": "<string>",
      "grace_deadline": {},
      "idle_timeout": {},
      "kind": "<string>",
      "last_activity": {},
      "machine_state": "<string>",
      "memoryMB": 123,
      "metadata": {},
      "paused_at": {},
      "sandboxID": "<string>",
      "startedAt": "<string>",
      "state": "<string>",
      "templateID": "<string>",
      "volumeMounts": [
        {
          "name": "<string>",
          "path": "<string>"
        }
      ],
      "wake_reason": {},
      "warnings": [
        {}
      ],
      "preservation": {
        "status": "<string>",
        "operationID": "<string>",
        "billing": "<string>",
        "recovered": true,
        "code": "<string>",
        "terminal": true,
        "message": "<string>",
        "nextAction": "<string>"
      }
    }
  ]
}

Authentication

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

Parameters

string

URL-encoded key=value labels to match, such as app=demo.

string

Only machines started after this RFC 3339 timestamp. Format: date-time.

string

default:"desc"

Sort by start time. Allowed values: "asc", "desc".

string

Filter by template identifier.

string

Search machine ID or display name.

string

Filter by machine lifetime. Allowed values: "temporary", "persistent".

string

default:"0"

Pagination offset from the X-Next-Token response header.

integer

default:100

Maximum machines per page. Minimum: 1. Maximum: 100.

string

default:"running,paused"

Comma-separated states to include: running, paused, or both.

curl --request GET \
  --url "https://api.bead.run/v2/sandboxes" \
  --header "X-API-Key: $BEAD_API_KEY"

Response

200

Successfully returned all running sandboxes.

object[]

Successfully returned all running sandboxes.

Show Properties

string

Alias of the template

string

required

deprecated

Identifier of the client

integer

required

CPU cores for the sandbox Format: int32. Minimum: 1.

integer

required

Disk size for the sandbox in MiB Format: int32. Minimum: 0.

string | null

required

Time when the sandbox will expire Format: date-time. May be null.

boolean

True when the snapshot a paused sandbox would resume from was taken while the sandbox guest agent was not responding. A plain resume of it is refused with 409 and error_code sandbox_snapshot_guest_agent_unresponsive, because restoring that memory would bring the unresponsive agent back; resume it without memory (memory: false), which cold-boots the sandbox from its disk. Omitted for a running sandbox and for a snapshot whose agent answered.

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

integer

required

Memory for the sandbox in MiB Format: int32. Minimum: 128.

object

String key/value labels attached to the machine. Agent setup and credential references use reserved bead.* keys. Additional keys accept string values.

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

Time when the sandbox was started Format: date-time.

string

required

State of the sandbox Allowed values: "running", "paused".

string

required

Identifier of the template from which is the sandbox created

object[]

At most one retained volume mounted at /data or /mnt/<name>.

Show Properties

string

required

Name of the volume

string

required

Path of the volume

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.

object

Preserved or lost source recovery state.

Show Properties

string

required

Recovery state. Allowed values: "preserved", "lost".

string

Recovery operation UUID when available.

string

required

Who funds the preserved source.

boolean

Whether the capture has recovered.

string

Machine recovery error identifier, including machine_lost.

boolean

Whether the execution state is terminal.

string

required

Explanation of the recovery state.

string

required

Recommended recovery action.

Errors

Status	Meaning
400	Invalid pagination or filters; legacy lists also reject results over 5000 entries (`admission_limit`).
401	Authentication credential is missing or rejected.
403	The credential lacks the required scope.
429	Request or resource admission limit exceeded (`admission_limit`). Follow limit.next_action and Retry-After when present.
503	Service or persistence is temporarily unavailable.

curl --request GET \
  --url "https://api.bead.run/v2/sandboxes" \
  --header "X-API-Key: $BEAD_API_KEY"

{
  "response": [
    {
      "alias": "<string>",
      "clientID": "<string>",
      "cpuCount": 123,
      "diskSizeMB": 123,
      "endAt": {},
      "envdUnresponsiveAtPause": true,
      "envdVersion": "<string>",
      "grace_deadline": {},
      "idle_timeout": {},
      "kind": "<string>",
      "last_activity": {},
      "machine_state": "<string>",
      "memoryMB": 123,
      "metadata": {},
      "paused_at": {},
      "sandboxID": "<string>",
      "startedAt": "<string>",
      "state": "<string>",
      "templateID": "<string>",
      "volumeMounts": [
        {
          "name": "<string>",
          "path": "<string>"
        }
      ],
      "wake_reason": {},
      "warnings": [
        {}
      ],
      "preservation": {
        "status": "<string>",
        "operationID": "<string>",
        "billing": "<string>",
        "recovered": true,
        "code": "<string>",
        "terminal": true,
        "message": "<string>",
        "nextAction": "<string>"
      }
    }
  ]
}

Start here

Endpoints

List machines

Authentication

Parameters

Response

200

Errors

​Authentication

​Parameters

​Response

​200

​Errors

Authentication

Parameters

Response

200

Errors