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

# Get machine details

> Inspect a machine’s connection, lifecycle, checkpoint, and recovery state.

## Authentication

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

## Parameters

**sandboxID** `string` *required*

Machine identifier returned by creation.

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

## Response

### 200

Successfully returned the sandbox.

**alias** `string`

Alias of the template

**allowInternetAccess** `boolean | null`

Whether internet access was explicitly enabled or disabled for the sandbox. Null means it was not explicitly set. May be `null`.

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

**domain** `string | null`

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

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

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

**envdAccessToken** `string`

Access token used for envd communication

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

**lifecycle** `object`

Sandbox lifecycle policy returned by sandbox info.

**Properties**

**autoResume** `boolean` *required*

Whether the sandbox can auto-resume.

**onTimeout** `string` *required*

Action taken when the sandbox times out. Allowed values: `"kill"`, `"pause"`.

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

**network** `object`

Network configuration object. This deployment rejects an explicit network configuration with 501 unsupported\_feature.

**Properties**

**allowOut** `string[]`

List of allowed destinations for egress traffic. Each entry can be a CIDR block (e.g. "8.8.8.8/32"), a bare IP address (e.g. "8.8.8.8"), or a domain name (e.g. "example.com", "\*.example.com"). Allowed entries always take precedence over denied entries. When allowOut contains a domain, the servers in dnsServers (8.8.8.8 by default) are also allowed.

**allowPublicTraffic** `boolean | null`

Whether sandbox URLs accept traffic without the sandbox's traffic access token. When omitted or null on create, the project's default applies, which is true unless the project changed it. May be `null`.

**denyOut** `string[]`

List of denied CIDR blocks or IP addresses for egress traffic. Domain names are not supported for deny rules.

**dnsServers** `string[]`

DNS servers the sandbox can reach when allowOut contains a domain. Each entry must be an IPv4 address, and all traffic to it is allowed. Omit it to allow the default nameserver 8.8.8.8, or pass an empty list to allow none. This does not change the sandbox's /etc/resolv.conf. Maximum items: `10`.

**egressProxy** `object | null`

SOCKS5 proxy for sandbox egress. Outbound TCP is tunneled through the proxy after allow/deny filtering; the sandbox is unaware. Domain-matched flows use remote DNS (ATYP=domain). May be `null`.

**Properties**

**address** `string` *required*

SOCKS5 proxy address in host:port format (e.g. "proxy.example.com:1080").

**password** `string`

Optional SOCKS5 password (RFC 1929), max 255 bytes. Maximum length: `255`.

**tls** `object | null`

TLS for the connection to the SOCKS5 proxy. The SOCKS5 negotiation and the tunneled traffic both run inside the TLS session, so the proxy credentials are not sent in the clear. This secures only the hop to the proxy; what the proxy does onward is its own concern. A half-close from the sandbox reaches the proxy as a TLS close\_notify, not a TCP FIN, and a proxy that treats close\_notify as a full close cuts the reply short. May be `null`.

**Properties**

**caCert** `string`

One or more PEM-encoded certificates to verify the proxy against, for a proxy fronted by a private CA. These replace the system trust store, which is what is used when this is omitted. Set this to use the same certificate verification for every request. Maximum length: `8192`.

**enabled** `boolean` *required*

Connect to the proxy over TLS. When false, no other field in this object may be set.

**serverName** `string`

Name to verify the proxy certificate against, and to send as SNI. Defaults to the host part of address. Set this only when the certificate does not match the address the proxy is reached at. Maximum length: `253`.

**username** `string`

Optional SOCKS5 username (RFC 1929), max 255 bytes. Maximum length: `255`.

**httpsPorts** `integer[]`

Sandbox ports that serve HTTPS rather than plaintext HTTP. Affects how the proxy reaches the service inside the sandbox; the public URL is HTTPS either way. Certificates are not verified, so self-signed ones work. The envd port (49983) cannot be listed. Maximum items: `128`.

**maskRequestHost** `string`

Specify host mask which will be used for all sandbox requests

**rules** `object`

Per-domain transform rules applied to matching outbound HTTPS requests. Keys may be exact DNS names (for example, "api.example.com") or a leading wildcard (for example, "*.example.com"), and are normalized to lowercase on write. Wildcards match subdomains at any depth but not the apex domain; a bare "*" is invalid. Exact rules take precedence, followed by the longest matching wildcard suffix, and matching rule sets are not merged. Broad wildcards such as "\*.com" are allowed and may expose transformed credentials to every matching destination the sandbox contacts. Rules do not grant network access; configure allowOut separately to permit the destination. Additional keys accept `object[]` values.

**Properties**

**\<key>** `object[]`

Network rules attached to this named network policy; explicit network configuration is not supported by this deployment.

**Properties**

**transform** `object`

Transformations applied to matching egress requests before forwarding.

**Properties**

**headers** `object`

HTTP headers to inject or override in matching requests. An existing header with the same name is replaced. Values are plain strings; secret resolution happens client-side before sending to the API. Additional keys accept `string` values.

**pauseMode** `string`

What the sandbox's latest pause saved. `full` saved the filesystem and the memory, and resuming restores the sandbox where it left off. `filesystem` saved only the filesystem, and resuming reboots the sandbox from disk. Returned for a paused sandbox once its pause has finished, and omitted while it is still pausing. Allowed values: `"full"`, `"filesystem"`.

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

**durability** `object`

Checkpoint durability and recovery state.

**Properties**

**mode** `string` *required*

Durability mode. Allowed values: `"host_local"`, `"bounded_checkpoint"`.

**remoteCheckpoint** `boolean`

Whether a remote checkpoint is available in host-local mode.

**checkpointIntervalSeconds** `integer`

Configured checkpoint interval in seconds.

**lastCommittedCheckpointAtMs** `integer | null`

Last committed checkpoint in Unix milliseconds. May be `null`.

**checkpointAgeMs** `integer | null`

Age of the last checkpoint in milliseconds. May be `null`.

**hostLost** `boolean`

Whether machine execution was lost.

**recoverable** `boolean`

Whether a committed checkpoint can be recovered.

**status** `string`

Checkpoint state. Allowed values: `"degraded"`, `"initializing"`, `"committed"`.

**message** `string`

Human-readable checkpoint status.

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