> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superserve.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Look up the status of a batch of sandboxes

> Reports the current status of each sandbox id in the batch, including ids whose sandbox was deleted. Every other read answers a deleted sandbox and one that never existed identically, so this is the way a caller holding stale references tells them apart. Ids the team does not own are returned as unknown, the same answer an id that never existed gets.




## OpenAPI

````yaml https://api.superserve.ai/openapi.yaml post /sandboxes/lookup
openapi: 3.1.0
info:
  title: Superserve API
  version: 0.1.0
  description: >
    Superserve provides sandbox infrastructure to run AI agents in the cloud.
    Powered by Firecracker MicroVMs.


    ## Sandbox lifecycle


    ```

    active <--> paused --> deleted

    ```


    A sandbox is `active` when running and `paused` after being paused. Resuming

    a paused sandbox returns it to `active`. Deleting releases all resources.


    | Endpoint | What it does |

    |----------|-------------|

    | `POST /sandboxes` | Create a new sandbox (optionally `from_template`) |

    | `PATCH /sandboxes/:id` | Partially update a running sandbox (e.g. network
    rules) |

    | `POST /sandboxes/:id/pause` | Snapshot full state, suspend the VM |

    | `POST /sandboxes/:id/resume` | Restore from snapshot, continue where it
    left off |

    | `DELETE /sandboxes/:id` | Delete sandbox and all resources |


    ## Sandbox environment


    By default sandboxes boot from the curated `superserve/base` template
    (Ubuntu 24.04,

    2 vCPU, 4096 MiB RAM, 8192 MiB disk, with Python 3.12, Node.js 22, npm, git,

    curl, and build-essential pre-installed). Callers can override with any
    template

    name (e.g. `superserve/python-3.11`, `superserve/node-22`) or a team-owned
    template UUID

    via the `from_template` field on `POST /sandboxes`.


    ## Files and commands


    `/files`, `/exec`, and `/exec/stream` run against a single sandbox and use

    its `X-Access-Token` (returned by create, resume, and activate), not the

    team API key. Two host forms reach them:


    - `https://sandbox.superserve.ai/...` with `X-Superserve-Sandbox-Id:
    <sandbox_id>`.

    - `https://boxd-{sandbox_id}.sandbox.superserve.ai/...` — no routing header
    needed.
  contact:
    name: Superserve Team
  license:
    name: Proprietary
servers:
  - url: https://api.superserve.ai
    description: Production
security: []
paths:
  /sandboxes/lookup:
    post:
      tags:
        - Sandboxes
      summary: Look up the status of a batch of sandboxes
      description: >
        Reports the current status of each sandbox id in the batch, including
        ids whose sandbox was deleted. Every other read answers a deleted
        sandbox and one that never existed identically, so this is the way a
        caller holding stale references tells them apart. Ids the team does not
        own are returned as unknown, the same answer an id that never existed
        gets.
      operationId: lookupSandboxes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sandbox_ids
              properties:
                sandbox_ids:
                  type: array
                  description: >
                    Sandbox ids to look up, in either public form. Duplicates
                    are collapsed. Page through a larger backlog a batch at a
                    time.
                  minItems: 1
                  maxItems: 1000
                  items:
                    $ref: '#/components/schemas/PublicSandboxId'
      responses:
        '200':
          description: Status for every id the team owns, and the rest as unknown.
          content:
            application/json:
              schema:
                type: object
                required:
                  - sandboxes
                  - unknown
                properties:
                  sandboxes:
                    type: array
                    description: One entry per id this team owns, deleted included.
                    items:
                      type: object
                      required:
                        - id
                        - status
                      properties:
                        id:
                          $ref: '#/components/schemas/PublicSandboxId'
                        status:
                          type: string
                          enum:
                            - starting
                            - active
                            - pausing
                            - paused
                            - resuming
                            - migrating
                            - failed
                            - deleted
                  unknown:
                    type: array
                    description: >
                      Ids with no sandbox for this team: never created, or
                      belonging to another team. Echoed exactly as submitted.
                    items:
                      $ref: '#/components/schemas/PublicSandboxId'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - apiKey: []
components:
  schemas:
    PublicSandboxId:
      type: string
      pattern: >-
        ^(sb-[a-z0-9]+-)?[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}$
      description: >
        Public sandbox ID: a bare UUID, or the region-tagged form
        `sb-<region>-<uuid>` (e.g. `sb-use-1b4e28ba-…`). Treat as an opaque
        string; the tagged form routes the request to the sandbox's home region.
        Endpoints accept both forms interchangeably.
    Error:
      type: object
      description: >
        Error envelope. `error.code` is a stable, machine-readable identifier

        (e.g. `bad_request`, `not_found`, `conflict`, `sandbox_pausing`,

        `rate_limited`, `too_many_builds`, `too_many_templates`,
        `too_many_sandboxes`,

        `image_pull_failed`, `step_failed`, `snapshot_failed`,

        `start_cmd_failed`, `ready_cmd_failed`, `capacity_unavailable`,

        `build_timed_out`, `infrastructure_failed`, `build_failed`,

        `trial_exhausted`, `trial_unavailable`, `trial_check_unavailable`,

        `free_allowance_exhausted`, `sandbox_exceeds_plan_limits`,

        `billing_ineligible`).

        `error.message` is human-readable and may change between releases;

        clients should branch on `code`, not `message`.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            action_url:
              type: string
              format: uri
              example: https://console.superserve.ai/plan-usage
              description: >
                Where to resolve the error, when there is a next step. Sent with
                `trial_exhausted`, `trial_unavailable` and
                `trial_check_unavailable`: the page where the team adds a card
                and chooses a plan.
  responses:
    BadRequest:
      headers:
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      headers:
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      headers:
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    RateLimitPolicy:
      description: >
        The budget that governs this request, as
        `"<scope>";q=<quota>;w=<seconds>;burst=<burst>`: which bucket it was
        charged against, how many requests that bucket sustains over the window,
        and the most that may be spent at once.


        Two buckets can refuse a request. Authenticated requests are normally
        charged against the per-team budget (`"team"`), but every request first
        passes a per-IP budget (`"ip"`) that blunts floods, and one refused
        there never reaches the team bucket. Read the scope rather than assuming
        which answered: behind a shared NAT or proxy it can be the IP budget
        even for a team well under its own limit.
      schema:
        type: string
    RateLimit:
      description: >
        What is left of the budget named by `RateLimit-Policy`, as
        `"<scope>";r=<remaining>;t=<seconds>`: `r` requests may be spent now,
        and `t` is the window that figure is good for.


        `t` is a pacing window, not a refill timer: spend no more than `r`
        within it, then read these headers again.


        `t` is the moment the bucket is full on any response these headers
        describe, with one exception: a `429` from the request budget itself,
        where `r` is zero and `t` is the wait for the single token you need,
        equal to `Retry-After`.


        A `429` from an endpoint's own limit — too many snapshots, templates,
        sandboxes — is not that case. It passed the request budget, so `r` is
        whatever was left, `t` is the ordinary full-refill wait, and no
        `Retry-After` is sent (except `host_capacity`, whose `Retry-After` is
        the wait for the host). Do not read these headers as the wait for that
        limit; they describe the request budget, which is not what refused the
        call.


        This and `RateLimit-Policy` are the current form of these headers.
        `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` carry the
        same numbers in the earlier form and are still sent, so existing clients
        keep working; new clients should prefer these two.
      schema:
        type: string
    RateLimitLimit:
      description: >
        Bucket capacity, in the same unit as `RateLimit-Remaining`. This is the
        burst, not the per-second rate: the budget is a token bucket, not a
        fixed window, so the sustained rate is in `RateLimit-Policy`.


        Earlier form; `RateLimit-Policy` carries the same capacity as `burst`.
      schema:
        type: integer
    RateLimitRemaining:
      description: >
        Tokens left in the bucket after this request. Present on any response,
        so a client can read its budget before starting a batch.
      schema:
        type: integer
    RateLimitReset:
      description: >
        Seconds until the bucket is full again from where it stands. Not a
        window boundary; there is no window. Never below 1.


        This is not `Retry-After`. On a request-budget `429`, `Retry-After` is
        when one more request may be sent and this is when the whole budget is
        back; they differ by roughly the burst. Sleep on `Retry-After` to send
        the next request, on this to restart a batch.


        It is also not `t` in `RateLimit`, which is the shorter pacing window on
        a `429` that the request budget itself produced. This field is always
        the full-refill timer, whatever the response.


        It always describes the request budget, which is not always what refused
        a `429` — see the `429` response description.
      schema:
        type: integer
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.