> ## 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. # Snapshot recent executions > Reads recent retained execution metadata, running executions first and then newest admission/completion. Output chunks are empty. Historical pagination is not supported. These reads never start a command, wake or resume a Sailbox, attach a command output consumer, or extend its idle lifetime. A non-running Sailbox, unsupported installed software, or a temporary observation failure returns 200 with unavailable_reason. This is distinct from an available empty result. Requires an organization API key or a valid Sail session bearer token. The Sailbox must belong to that organization. Private Sailboxes require their creator or an organization admin supplying an owner override reason. Output can contain arbitrary bytes; decode data from base64. All int64 values are decimal strings. ## OpenAPI ````yaml /sailbox-openapi.json get /sailboxes/{sailbox_id}/executions openapi: 3.1.0 info: title: Sail Sailbox API version: '2026-10-04' description: >- Create and operate Sailboxes over HTTP. Sailboxes are fast-booting virtual machines that you can pause, resume, and checkpoint. Run commands, stream files, manage lifecycle and networking, and inspect usage. Turning on SSH and building an image still require an SDK or the CLI. 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: Exec description: Run commands and control their standard input and terminals. - name: Files description: Stream regular files into and out of a Sailbox. - name: Networking description: >- Publish ports, serve them on hostnames you own, and identify a Sailbox to other Sailboxes. - name: Secrets description: >- Organization values that egress policy rules can add to matching requests. Sail never returns a stored value. - name: Egress policies description: >- What a Sailbox may connect to, and what happens to the HTTPS requests it sends. - 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/{sailbox_id}/executions: get: tags: - Exec summary: Snapshot recent executions description: >- Reads recent retained execution metadata, running executions first and then newest admission/completion. Output chunks are empty. Historical pagination is not supported. These reads never start a command, wake or resume a Sailbox, attach a command output consumer, or extend its idle lifetime. A non-running Sailbox, unsupported installed software, or a temporary observation failure returns 200 with unavailable_reason. This is distinct from an available empty result. Requires an organization API key or a valid Sail session bearer token. The Sailbox must belong to that organization. Private Sailboxes require their creator or an organization admin supplying an owner override reason. Output can contain arbitrary bytes; decode data from base64. All int64 values are decimal strings. operationId: listSailboxExecutions parameters: - $ref: '#/components/parameters/SailboxId' - name: execution_id in: query required: false schema: type: string maxLength: 262144 description: >- Exact execution id, URL-encoded and limited to 256 KiB of UTF-8. Empty or omitted selects the current window. - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 64 default: 32 description: >- Maximum execution metadata records per response. Byte budgets may return fewer. - name: max_bytes in: query required: false schema: type: integer minimum: 1024 maximum: 262144 default: 65536 description: >- Maximum decoded output bytes across all chunks per response. The executions endpoint validates this bound but returns no output. - $ref: '#/components/parameters/OwnerOverrideReason' responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/SailboxExecutionObservationResponse' examples: available: value: executions: - execution_id: exec_123 argv: - echo - hi state: EXEC_RECORD_STATE_SUCCEEDED started_at_unix_nanos: '1792440000000000000' completed_at_unix_nanos: '1792440001000000000' return_code: 0 pty: false stdout_truncated: false stderr_truncated: false output_evicted: false metadata_truncated: false chunks: [] unavailable_reason: '' history_truncated: false unavailable: value: executions: [] chunks: [] unavailable_reason: sailbox_sleeping history_truncated: false headers: Cache-Control: schema: type: string const: private, no-store description: Observation responses must not be cached. '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_limit_gib for size m must be between 8 and 128 type: invalid_request_error param: null code: null '401': description: The bearer API key or Sail session token 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 Sailbox belongs to another organization, or private access is not authorized. 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 '404': description: No Sailbox with that id exists in your organization. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: message: sailbox "sb_9c8f1e2a-3b4d-4f5a-8c7e-1d2f3a4b5c6d" not found type: not_found_error param: null code: null '429': description: >- The request concurrency limit or execution metadata read budget was exceeded. See the error message before retrying. 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' security: - BearerAuth: [] - SailSessionToken: [] components: parameters: SailboxId: name: sailbox_id in: path required: true schema: type: string description: >- Id of the Sailbox, as returned by create. It is `sb_` followed by a UUID. OwnerOverrideReason: name: X-Sail-Owner-Override-Reason in: header required: false schema: type: string pattern: ^[ -~]*$ description: >- Lets an organization admin operate a `private` Sailbox someone else created. Say why in plain text; the reason goes into your organization's audit log, and the operation is refused without it. Ignored on Sailboxes you could already operate. Pause, resume, sleep, scheduled wake, upgrade, reboot, and terminate accept an override, and so does deleting a checkpoint taken from the Sailbox. Setting an egress policy accepts one too. Running commands and moving files accept one through an SDK or the CLI. Publishing and unpublishing ports, adding and removing custom domains, checkpointing, and creating from a checkpoint stay with the creator. schemas: SailboxExecutionObservationResponse: type: object additionalProperties: false description: >- A bounded snapshot with explicit defaults. It is not a complete or offline execution history. properties: executions: type: array maxItems: 64 items: $ref: '#/components/schemas/SailboxExecutionObservation' chunks: type: array maxItems: 128 items: $ref: '#/components/schemas/SailboxObservedExecChunk' description: >- Independent stream tails. Replace the previous snapshot; do not append. Always empty for the executions listing. unavailable_reason: type: string description: >- Empty when this observation is available. A nonempty reason means unavailable, not an empty history. sailbox_ means the Sailbox is not running. unsupported_guest means its installed software does not support observation. placement_unavailable, guest_unavailable and worker_unreachable indicate an unavailable or changing connection. execution_not_retained means the selected execution is absent from retained metadata. observation_unavailable means the read could not be completed. Treat unknown future reasons as unavailable. history_truncated: type: boolean description: >- The output window or metadata budget omitted records, or a record disappeared during the read. Historical pagination is not supported. required: - executions - chunks - unavailable_reason - history_truncated ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorObject' SailboxExecutionObservation: type: object additionalProperties: false properties: execution_id: type: string maxLength: 524288 argv: type: array maxItems: 128 items: type: string maxLength: 4096 description: >- Command arguments, limited to 128 entries and a shared 4 KiB UTF-8 budget. state: type: string enum: - EXEC_RECORD_STATE_UNSPECIFIED - EXEC_RECORD_STATE_RUNNING - EXEC_RECORD_STATE_SUCCEEDED - EXEC_RECORD_STATE_FAILED - EXEC_RECORD_STATE_TIMED_OUT - EXEC_RECORD_STATE_CANCELED - EXEC_RECORD_STATE_INTERRUPTED started_at_unix_nanos: type: string pattern: ^-?[0-9]+$ maxLength: 20 description: >- Start time in Unix nanoseconds, encoded as a decimal int64 string. Zero means unavailable. completed_at_unix_nanos: type: string pattern: ^-?[0-9]+$ maxLength: 20 description: >- Completion time in Unix nanoseconds, encoded as a decimal int64 string. Zero means unavailable or still running. return_code: type: integer format: int32 pty: type: boolean description: >- Whether this execution uses a pseudo-terminal, with merged output on stdout. stdout_truncated: type: boolean stderr_truncated: type: boolean output_evicted: type: boolean description: >- Whether retained output was evicted. Metadata can remain after output is gone. metadata_truncated: type: boolean description: Whether command arguments were shortened to the metadata budget. required: - execution_id - argv - state - started_at_unix_nanos - completed_at_unix_nanos - return_code - pty - stdout_truncated - stderr_truncated - output_evicted - metadata_truncated SailboxObservedExecChunk: type: object additionalProperties: false properties: execution_id: type: string maxLength: 524288 stream: type: string enum: - stdout - stderr data: type: string format: byte maxLength: 349528 description: >- Base64-encoded bytes. The combined decoded data in a response is bounded by max_bytes. Empty data can indicate missing output. source: type: string enum: - live - retained description: >- Live output preserves raw bytes. Retained tails use the existing sanitized UTF-8 text representation. truncated: type: boolean description: >- Earlier bytes were dropped or exceed this stream's share of the snapshot budget. missing: type: boolean description: >- Retained output is no longer available; this does not mean the command produced no output. required: - execution_id - stream - data - source - truncated - missing 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`, `quota_exceeded_error`, `not_implemented_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. Errors relayed from the Sailbox runtime carry its status token, for example `already_exists` or `failed_precondition` on a 409, which the HTTP status alone does not distinguish. billing_url: type: string format: uri description: Page where you add credits. Sent with a 402. additionalProperties: true 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 SailSessionToken: type: http scheme: bearer bearerFormat: Sail session token description: >- A valid signed Sail application session token carrying organization and user access. ````