> ## Documentation Index > Fetch the complete documentation index at: https://docs.sailresearch.com/llms.txt > Use this file to discover all available pages before exploring further. # List Sailboxes > Returns Sailboxes in your organization, most recently active first. Terminated Sailboxes stay in the list, so filter by `status` if you only want live ones. ## OpenAPI ````yaml /sailbox-openapi.json get /sailboxes openapi: 3.1.0 info: title: Sail Sailbox API version: '2026-07-26' description: >- Create and operate Sailboxes over HTTP. Sailboxes are fast-booting virtual machines that you can pause, resume, checkpoint, and fork. Three things need an SDK or the CLI: running commands and moving files, turning on SSH, and building an image. Once SSH is on you can use `ssh` and `scp` for the first of those. See the [HTTP API guide](/sailboxes-http-api). servers: - url: https://sailbox-api.sailresearch.com/v1 security: - BearerAuth: [] tags: - name: Apps description: Groups that own Sailboxes. One app per workload. - name: Lifecycle description: >- A Sailbox's whole life: create it, watch it, stop and start it, terminate it. - name: Checkpoints description: Save a Sailbox to start from later, and copy a running one. - name: Networking description: >- Publish ports, serve them on hostnames you own, and identify a Sailbox to other Sailboxes. - name: Volumes description: >- Shared storage that outlives any one Sailbox. Alpha: these endpoints can still change. - name: SSH access description: Certificates for connecting to a Sailbox with `ssh`. - name: Usage description: Resource usage and spend. - name: Identity description: Who your API key belongs to. paths: /sailboxes: get: tags: - Lifecycle summary: List Sailboxes description: >- Returns Sailboxes in your organization, most recently active first. Terminated Sailboxes stay in the list, so filter by `status` if you only want live ones. operationId: listSailboxes parameters: - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 50 description: How many Sailboxes to return. - name: offset in: query schema: type: integer minimum: 0 maximum: 100000 default: 0 description: How many Sailboxes to skip before the page starts. - name: app in: query schema: type: string description: Only return Sailboxes in this app id. - name: status in: query schema: type: string description: >- Only return Sailboxes in this status. `failed` also returns `create_failed` and `interrupted_unsafe_to_retry`. - name: exclude_status in: query schema: type: string description: >- Leave out Sailboxes in any of these statuses, written as a comma-separated list. Each name is matched exactly, so `failed` here leaves out only `failed`. - name: search in: query schema: type: string description: >- Only return Sailboxes matching this text. It is matched against the Sailbox name and id and against the name and id of the app it belongs to. - name: manageable_by_caller in: query schema: type: boolean default: false description: >- Only return Sailboxes this key can operate without an owner override. A `private` Sailbox someone else created is left out even for an organization admin. - name: order in: query schema: type: string enum: - newest_active - newest_created - '' default: newest_active description: >- `newest_active` groups by state, most recently changed first within each group: `running` and `creating`, then `paused`, `sleeping`, and `interrupted_restorable`, then `failed`, `create_failed`, and `interrupted_unsafe_to_retry`, then everything else. `newest_created` sorts purely by creation time. responses: '200': description: A page of Sailboxes. content: application/json: schema: $ref: '#/components/schemas/SailboxList' example: data: - sailbox_id: sb_9c8f1e2a-3b4d-4f5a-8c7e-1d2f3a4b5c6d name: worker-1 app_id: app_0f6a2c31-8b4d-4e7a-9c15-2d8e6f4a1b03 app_name: batch-jobs image_id: >- sha256:7b1e4a0d93c25f68a1d4f7b0c3e29a5d81f6b4c07e2a9d3f5b8c1e6a04d7f293 status: running architecture: amd64 vcpu_count: 4 memory_mib: 32768 state_disk_size_gib: 128 cpu_used_vcpu: 1.8 memory_used_bytes: 4294967296 disk_used_bytes: 10737418240 error_message: null deprecation: null guest_schema_version: 71 created_by_user_id: user_9z8y visibility: org started_at: '2026-07-20T18:04:19Z' last_checkpointed_at: null checkpoint_generation: 0 created_at: '2026-07-20T18:04:11Z' updated_at: '2026-07-20T18:31:02Z' can_pause: true can_sleep: true can_resume: false can_terminate: true limit: 50 offset: 0 total: 1 has_more: false '400': description: >- The request was rejected. See the error message for the offending field. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: memory_gib for size m must be between 8 and 128 type: invalid_request_error param: null code: null '401': description: The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: Invalid API key type: authentication_error param: null code: invalid_api_key '402': description: >- The organization is out of credits. The error carries a `billing_url` pointing at the page where you add them. Retry once you have. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: >- Your API key has been disabled due to insufficient credits. Visit https://app.sailresearch.com/billing to add credits. type: billing_error param: null code: credits_exhausted billing_url: https://app.sailresearch.com/billing '403': description: The API key is not allowed to perform this operation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: sailboxes require an organization-scoped API key type: permission_error param: null code: null '429': description: >- For its first ten minutes a new organization is capped on how many requests it can have in flight at once, and yours is over that cap. The request never started, so retry it unchanged after the delay in the `Retry-After` header. The limit clears as those requests finish. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: >- Too many concurrent requests. Please retry after some of your organization's in-flight requests complete. type: rate_limit_error param: null code: rate_limited headers: Retry-After: $ref: '#/components/headers/RetryAfter' '500': description: Server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: failed to fetch sailbox type: server_error param: null code: null '503': description: >- Sail is momentarily unavailable. Retry after the delay in the `Retry-After` header when one is present, and with backoff otherwise. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: Authentication service unavailable type: server_error param: null code: null headers: Retry-After: $ref: '#/components/headers/RetryAfter' components: schemas: SailboxList: type: object properties: data: type: array items: $ref: '#/components/schemas/Sailbox' description: The requested page of Sailboxes. limit: type: integer description: Page size that was applied. offset: type: integer description: Offset that was applied. total: type: integer description: Total number of Sailboxes matching the filters. has_more: type: boolean description: Whether another page follows this one. required: - data - limit - offset - total - has_more ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' Sailbox: type: object description: >- 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. properties: sailbox_id: type: string description: Unique id of the Sailbox. name: type: string description: >- 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: type: string description: Id of the app the Sailbox belongs to. app_name: type: string description: Name of the app the Sailbox belongs to. image_id: type: string description: >- Id of the built image the Sailbox boots from. Two Sailboxes created from the same `image` share this id. status: type: string description: >- 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: type: string description: CPU architecture the Sailbox runs on. vcpu_count: type: integer description: Virtual CPUs allocated to the Sailbox. memory_mib: type: integer description: Memory limit in MiB. state_disk_size_gib: type: integer description: Disk limit in GiB. cpu_used_vcpu: type: number description: >- Virtual CPUs in use in the most recent sample. `0` when there is no recent sample. memory_used_bytes: type: integer description: >- Memory in use in the most recent sample. `0` when there is no recent sample. format: int64 disk_used_bytes: type: integer description: >- Disk in use in the most recent sample. `0` when there is no recent sample. format: int64 error_message: oneOf: - type: string - type: 'null' description: Why the Sailbox failed, when it failed. deprecation: oneOf: - $ref: '#/components/schemas/SailboxDeprecation' - type: 'null' description: >- 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: oneOf: - type: integer format: int64 - type: 'null' description: >- Version of the Sail runtime inside the Sailbox. `null` when the version is not known. created_by_user_id: oneOf: - type: string - type: 'null' description: >- User whose key created the Sailbox. `null` when a service key created it. visibility: oneOf: - type: string - type: 'null' description: >- `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: oneOf: - type: string format: date-time - type: 'null' description: >- When the Sailbox first started running. It is not rewritten when a Sailbox resumes. last_checkpointed_at: oneOf: - type: string format: date-time - type: 'null' description: When the Sailbox last saved its state. checkpoint_generation: type: integer description: >- 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. format: int64 created_at: type: string format: date-time description: When the Sailbox was created. updated_at: type: string format: date-time description: When the Sailbox last changed. can_pause: type: boolean description: >- Whether pausing would change this Sailbox now. False once it is paused. can_sleep: type: boolean description: >- Whether sleeping would change this Sailbox now. False once it is asleep. can_resume: type: boolean description: >- Whether resuming would change this Sailbox now. False once it is running. can_terminate: type: boolean description: >- Whether terminating would change this Sailbox now. False once it is shutting down or gone. required: - sailbox_id - name - app_id - app_name - image_id - status - architecture - vcpu_count - memory_mib - state_disk_size_gib - cpu_used_vcpu - memory_used_bytes - disk_used_bytes - error_message - deprecation - guest_schema_version - created_by_user_id - visibility - started_at - last_checkpointed_at - checkpoint_generation - created_at - updated_at - can_pause - can_sleep - can_resume - can_terminate ErrorObject: type: object required: - message - type - param - code properties: message: type: string description: Human-readable description of what went wrong. type: type: string description: >- Error category: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `not_found_error`, `conflict_error`, `rate_limit_error`, or `server_error`. param: oneOf: - type: string - type: 'null' description: >- The request field the error refers to, when the error is about one field. code: oneOf: - type: string - type: integer - type: 'null' description: Stable short code for the error, when one applies. billing_url: type: string format: uri description: Page where you add credits. Sent with a 402. additionalProperties: true SailboxDeprecation: type: object description: >- Set when the Sailbox runs an outdated runtime and you can upgrade it now. `null` when there is nothing to act on, including when an upgrade is already under way or your key cannot operate this Sailbox. properties: deadline: type: string description: >- Date after which the Sailbox may be restarted automatically to upgrade it. examples: - '2026-09-01' message: type: string description: Explanation you can show to whoever owns the Sailbox. required: - deadline - message headers: RetryAfter: description: >- How many seconds to wait before retrying. On a 429 it also means the request never started, so the retry can reuse the same `Idempotency-Key`. schema: type: integer minimum: 0 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key ````