Endpoints
List running machines
List running machines with metadata filters; use the v2 route for pagination.
GET
/
sandboxes
curl --request GET \
--url "https://api.bead.run/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 theAuthorization: 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.
curl --request GET \
--url "https://api.bead.run/sandboxes" \
--header "X-API-Key: $BEAD_API_KEY"
Response
200
Successfully returned all running sandboxes.object[]
Successfully returned all running sandboxes.
Show Properties
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[]
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
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. |
⌘I
curl --request GET \
--url "https://api.bead.run/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>"
}
}
]
}