Skip to main content
GET
Get a sandbox
Retrieve metadata for a single sandbox. status: "resume_failed" is a nonterminal failure of a resume attempt. The sandbox keeps its identity and original snapshot_id; optional error_details retains the diagnosis. Reading metadata does not retry the failure. Use Resume Sandbox to retry explicitly. If status is pending with retained_runtime.state: "resume_uncertain", execution has not safely settled. Keep inspecting instead of treating it as a retryable failure. See Recover from a failed resume. The response includes ingress_endpoint, the base ingress origin for this sandbox’s current placement, and sandbox_url, the sandbox-specific management URL derived from it. The response’s auto_resume boolean tells you whether proxy traffic may wake the sandbox while suspended. false does not indicate that the sandbox is currently suspended; check status separately. Reading this metadata does not wake a suspended sandbox.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

sandbox_id
string
required

The ID of the sandbox.

Response

Sandbox retrieved successfully

auto_resume
boolean
required

Whether proxy traffic may wake the sandbox while suspended. Defaults to true on creation. Explicit resume does not change this setting, and copies inherit it. Check status separately to determine whether the sandbox is currently suspended.

id
string
required
namespace
string
required
status
enum<string>
required
Available options:
pending,
running,
snapshotting,
suspending,
suspended,
terminated,
resume_failed
created_at
integer<int64>
required

Milliseconds since Unix epoch.

resources
object
required
timeout_secs
integer<int64>
required
allow_unauthenticated_access
boolean
required

Whether sandbox ingress may route requests without auth validation.

image
string
pending_reason
string | null

Present when status is pending.

outcome
string | null

Platform-specific termination outcome string returned for completed sandboxes.

termination_reason
string | null

Typed reason the sandbox terminated (e.g. FileSystemNotFound, FileSystemSnapshotNotFound, ImageNotFound, no_capacity when a max_pending_secs bound ran out while waiting for a host, cancelled when a pending sandbox was deleted). Present on failed terminations.

error_details
string | null

Optional diagnosis for termination or a recoverable resume failure. An accepted explicit resume clears the previous diagnosis. Inspect status rather than classifying failure from this text.

container_id
string | null
executor_id
string | null
ingress_endpoint
string | null

Canonical server-provided base for sandbox-specific ingress.

sandbox_url
string | null

Sandbox-specific management URL derived from ingress_endpoint.

pool_id
string | null
network_policy
null | object

Egress network policy currently applied to the sandbox. null when egress is unrestricted.

exposed_ports
integer<int32>[] | null

Additional routable ingress ports. When null, only the management port 9501 is routable.

Required range: 1 <= x <= 65535
template_id
string | null
name
string | null
file_systems
object[]

Filesystems currently mounted into the sandbox.

snapshot_id
string | null

Retained checkpoint ID. A recoverable resume failure preserves the original checkpoint for an explicit retry.