> ## 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 image builds

> Returns your organization's image builds, newest first. See [Build queue](/sailboxes-images#build-queue) for when a build is `queued`.

This endpoint is rate limited for your organization. If you call it repeatedly, wait a few seconds between calls.



## OpenAPI

````yaml /sailbox-openapi.json get /sailbox-image-builds
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: Image builds
    description: >-
      Watch and cancel the image builds your organization starts with an SDK or
      the CLI.
  - 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:
  /sailbox-image-builds:
    get:
      tags:
        - Image builds
      summary: List image builds
      description: >-
        Returns your organization's image builds, newest first. See [Build
        queue](/sailboxes-images#build-queue) for when a build is `queued`.


        This endpoint is rate limited for your organization. If you call it
        repeatedly, wait a few seconds between calls.
      operationId: listImageBuilds
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
          description: How many builds to return.
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 100000
            default: 0
          description: How many builds to skip before the page starts.
        - name: status
          in: query
          schema:
            type: string
          description: >-
            Only return builds in any of these statuses, written as a
            comma-separated list: `queued`, `building`, `ready`, `failed`, or
            `cancelled`.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageBuildList'
              example:
                data:
                  - build_id: 5e2c9a47-1d8b-4f36-a09e-7c4b2d6f8a13
                    image_id: >-
                      sha256:7b1e4a0d93c25f68a1d4f7b0c3e29a5d81f6b4c07e2a9d3f5b8c1e6a04d7f293
                    status: queued
                    architecture: arm64
                    created_at: '2026-05-04T17:02:11Z'
                    started_at: null
                    finished_at: null
                    error_message: null
                limit: 50
                offset: 0
                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: >-
                    status must be one of queued, building, ready, failed,
                    cancelled
                  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: >-
            Too many requests in flight, or the organization is at a limit. A
            `Retry-After` header means the request never started, so retry it
            unchanged after that delay. Without one, the request ran and hit the
            limit `message` names. Some of those clear on their own, such as a
            shortage of public ports; others need you to free something up
            first. Send the request again once the cause is gone.
          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:
    ImageBuildList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ImageBuild'
        limit:
          type: integer
        offset:
          type: integer
        has_more:
          type: boolean
          description: Whether another page follows this one.
      required:
        - data
        - limit
        - offset
        - has_more
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
    ImageBuild:
      type: object
      properties:
        build_id:
          type: string
          description: Id of the build.
        image_id:
          type: string
          description: Id of the image the build produces.
        status:
          type: string
          description: >-
            A build is `queued` while it waits to start, then `building`, and it
            ends as `ready`, `failed`, or `cancelled`. Sail can add statuses
            later, so handle a value you do not recognize.
        architecture:
          type: string
          description: CPU architecture the image is built for.
        created_at:
          type: string
          format: date-time
          description: When the build was requested.
        started_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the build last started running. Null while the build is queued,
            and for a build that never ran.
        finished_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the build became ready, failed, or was cancelled. Null until
            then.
        error_message:
          type:
            - string
            - 'null'
          description: Why the build failed or was cancelled. Null for any other status.
      required:
        - build_id
        - image_id
        - status
        - architecture
        - created_at
        - started_at
        - finished_at
        - error_message
    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

````