Skip to main content
GET
Retrieve a Sailbox

Authorizations

Authorization
string
header
required

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

Path Parameters

sailbox_id
string
required

Id of the Sailbox, as returned by create. It is sb_ followed by a UUID.

Pattern: ^sb_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Response

The Sailbox.

A Sailbox and its latest observed resource usage. The can_ flags are hints for deciding which actions are worth offering. They are all false on a private Sailbox you did not create, even where X-Sail-Owner-Override-Reason would still let you act.

sailbox_id
string
required

Unique id of the Sailbox.

name
string
required

The Sailbox's display name: the one you gave at create, restore, or fork time, or one derived from the source when you left it out.

app_id
string
required

Id of the app the Sailbox belongs to.

app_name
string
required

Name of the app the Sailbox belongs to.

image_id
string
required

Id of the built image the Sailbox boots from. Two Sailboxes created from the same image share this id.

status
string
required

Current state of the Sailbox. Values in use today are creating, running, paused, sleeping, terminating, terminated, failed, create_failed, interrupted_restorable, and interrupted_unsafe_to_retry. New values can appear over time, so treat this as an open set.

architecture
string
required

CPU architecture the Sailbox runs on.

vcpu_count
integer
required

Virtual CPUs allocated to the Sailbox.

memory_mib
integer
required

Memory limit in MiB.

state_disk_size_gib
integer
required

Disk limit in GiB.

cpu_used_vcpu
number
required

Virtual CPUs in use in the most recent sample. 0 when there is no recent sample.

memory_used_bytes
integer<int64>
required

Memory in use in the most recent sample. 0 when there is no recent sample.

disk_used_bytes
integer<int64>
required

Disk in use in the most recent sample. 0 when there is no recent sample.

error_message
string | null
required

Why the Sailbox failed, when it failed.

deprecation
object | null
required

Upgrade notice when this Sailbox has a deadline to act on and your credential can act on it. null otherwise, which is the usual case.

guest_schema_version
integer<int64> | null
required

Version of the Sail runtime inside the Sailbox. null when the version is not known.

created_by_user_id
string | null
required

User whose key created the Sailbox. null when a service key created it.

visibility
string | null
required

private means only the creator can operate the Sailbox, apart from the operations an organization admin can take with X-Sail-Owner-Override-Reason. org or null means anyone in the organization can operate it.

started_at
string<date-time> | null
required

When the Sailbox first started running. It is not rewritten when a Sailbox resumes.

last_checkpointed_at
string<date-time> | null
required

When the Sailbox last saved its state.

checkpoint_generation
integer<int64>
required

Checkpoint counter for the Sailbox. It goes up by one every time the Sailbox saves its state, which includes pausing and sleeping. Compare it across two reads to tell whether the Sailbox saved again in between.

created_at
string<date-time>
required

When the Sailbox was created.

updated_at
string<date-time>
required

When the Sailbox last changed.

can_pause
boolean
required

Whether pausing would change this Sailbox now. False once it is paused.

can_sleep
boolean
required

Whether sleeping would change this Sailbox now. False once it is asleep.

can_resume
boolean
required

Whether resuming would change this Sailbox now. False once it is running.

can_terminate
boolean
required

Whether terminating would change this Sailbox now. False once it is shutting down or gone.