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

# List machines

> Page through your machines with state, metadata, and start-time filters.

## Authentication

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

## Parameters

**metadata** `string`

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

**startedAfter** `string`

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

**order** `string` (default: desc)

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

**template** `string`

Filter by template identifier.

**search** `string`

Search machine ID or display name.

**kind** `string`

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

**nextToken** `string` (default: 0)

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

**limit** `integer` (default: 100)

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

**state** `string` (default: running,paused)

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

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
curl --request GET \
  --url "https://api.bead.run/v2/sandboxes" \
  --header "X-API-Key: $BEAD_API_KEY"
```

## Response

### 200

Successfully returned all running sandboxes.

**response** `object[]`

Successfully returned all running sandboxes.

**Properties**

**alias** `string`

Alias of the template

**clientID** `string` *required* *deprecated*

Identifier of the client

**cpuCount** `integer` *required*

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

**diskSizeMB** `integer` *required*

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

**endAt** `string | null` *required*

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

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

**envdVersion** `string` *required*

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

**memoryMB** `integer` *required*

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

**metadata** `object`

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

**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` *required*

Identifier of the sandbox

**startedAt** `string` *required*

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

**state** `string` *required*

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

**templateID** `string` *required*

Identifier of the template from which is the sandbox created

**volumeMounts** `object[]`

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

**Properties**

**name** `string` *required*

Name of the volume

**path** `string` *required*

Path of the volume

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

**preservation** `object`

Preserved or lost source recovery state.

**Properties**

**status** `string` *required*

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

**operationID** `string`

Recovery operation UUID when available.

**billing** `string` *required*

Who funds the preserved source.

**recovered** `boolean`

Whether the capture has recovered.

**code** `string`

Machine recovery error identifier, including machine\_lost.

**terminal** `boolean`

Whether the execution state is terminal.

**message** `string` *required*

Explanation of the recovery state.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.