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

# List sandboxes

> Returns one newest-first page of the organization's complete sandbox history.



## OpenAPI

````yaml /api-reference/openapi.yaml get /sandboxes
openapi: 3.1.0
info:
  title: Thunder Sandbox API
  version: '1.0'
  description: Create, inspect, list, and stop Thunder sandboxes.
  contact:
    name: Thunder Compute Support
    url: https://www.thundercompute.com/contact
    email: support@thundercompute.com
servers:
  - url: https://api.thundercompute.com:8443/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Sandboxes
    description: Short-lived isolated compute environments.
paths:
  /sandboxes:
    get:
      tags:
        - Sandboxes
      summary: List sandboxes
      description: >-
        Returns one newest-first page of the organization's complete sandbox
        history.
      operationId: listSandboxes
      parameters:
        - name: limit
          in: query
          description: Number of sandboxes to return.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: page_token
          in: query
          description: Opaque continuation token returned by the previous page.
          schema:
            type: string
      responses:
        '200':
          description: One page of sandbox history.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  schemas:
    SandboxListResponse:
      type: object
      required:
        - sandboxes
      properties:
        sandboxes:
          type: array
          items:
            $ref: '#/components/schemas/Sandbox'
        next_page_token:
          type: string
          description: Opaque token for the next page; absent on the last page.
    Sandbox:
      type: object
      required:
        - id
        - name
        - status
        - spec
        - network_policy
        - lifetime
        - created_at
      properties:
        id:
          type: string
          example: sbx-0123456789abcdef
        name:
          type: string
          example: training-run
        status:
          type: string
          enum:
            - pending
            - starting
            - running
            - stopping
            - stopped
            - failed
        spec:
          $ref: '#/components/schemas/SandboxResourceSpec'
        network_policy:
          $ref: '#/components/schemas/SandboxNetworkPolicy'
        lifetime:
          $ref: '#/components/schemas/SandboxLifetime'
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
          description: Present only when a positive TTL is enforced.
        ssh:
          $ref: '#/components/schemas/SandboxSSHConnection'
        failure_code:
          type: string
          description: Machine-readable reason, present only for failures.
        failure:
          type: string
          description: Human-readable reason, present only for failures.
    Error:
      type: object
      required:
        - error
        - message
        - code
      properties:
        error:
          type: string
          description: Stable machine-readable error code.
          example: invalid_request
        message:
          type: string
          description: Human-readable explanation.
          example: Invalid request body
        code:
          type: integer
          description: HTTP status code.
          example: 400
    SandboxResourceSpec:
      type: object
      required:
        - cpu_count
        - memory_gib
        - storage_gib
      description: >-
        GPU type and count must be supplied together. Supported types and ranges
        depend on the organization's sandbox configuration.
      properties:
        cpu_count:
          type: integer
          format: uint32
          minimum: 1
          description: Number of vCPUs.
        memory_gib:
          type: integer
          format: uint32
          minimum: 1
          description: Memory in GiB.
        storage_gib:
          type: integer
          format: uint32
          minimum: 1
          description: Ephemeral disk size in GiB.
        gpu_type:
          type: string
          description: GPU type such as H100. Omit with gpu_count for CPU-only.
        gpu_count:
          type: integer
          format: uint32
          minimum: 1
          description: Number of GPUs. Supply together with gpu_type.
    SandboxNetworkPolicy:
      type: object
      required:
        - internet_access
      properties:
        internet_access:
          type: string
          enum:
            - closed
            - open
            - restricted
          description: >-
            closed blocks external egress; open permits public internet;
            restricted enforces the supplied CIDR and domain controls.
        cidr_allowlist:
          type: array
          description: IPv4 CIDRs reachable under restricted access.
          items:
            type: string
            example: 203.0.113.0/24
        domain_allowlist:
          type: array
          description: >-
            DNS names resolvable under restricted access. A bare name is exact;
            *.example.com includes subdomains; * permits all names.
          items:
            type: string
            example: '*.example.com'
    SandboxLifetime:
      type: object
      required:
        - enforce_ttl
      properties:
        enforce_ttl:
          type: boolean
          description: Whether Thunder automatically stops the sandbox.
        max_ttl_seconds:
          type: integer
          format: uint32
          minimum: 0
          description: >-
            Lifetime from creation in seconds. Use a positive value when
            enforce_ttl is true.
        max_grace_seconds:
          type: integer
          format: uint32
          minimum: 0
          description: >-
            Requested graceful-shutdown budget in seconds; the platform may
            enforce a lower limit.
    SandboxSSHConnection:
      type: object
      description: Present only while the sandbox is running.
      required:
        - host
        - port
        - user
      properties:
        host:
          type: string
        port:
          type: integer
          format: uint32
        user:
          type: string
          example: ubuntu
  responses:
    BadRequest:
      description: Invalid request or pagination parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, invalid, or expired bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Sandbox access is not enabled for the organization.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded. Honor the Retry-After header.
      headers:
        Retry-After:
          description: Seconds until another request should be attempted.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Sandbox request failed unexpectedly.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unavailable:
      description: >-
        Capacity, access verification, control plane, or scheduler is
        unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API token
      description: API token created in the Thunder console.

````