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

# List Sandboxes

> Your sandboxes, newest first: every one that exists, plus failed ones. Destroyed sandboxes are not listed. Not paginated.

`meta.used` is how many slots your sandboxes take, and `meta.max` how many your account level allows. `meta.ever_used` is true once the account has created a sandbox.

While sandboxes are switched off on the platform, `data` is empty.



## OpenAPI

````yaml GET /sandboxes
openapi: 3.0.3
info:
  title: CloudBlast API
  description: >-
    The CloudBlast V2 API provides a modern RESTful interface for managing your
    cloud infrastructure programmatically. All responses follow a consistent `{
    "data": ... }` or `{ "error": ... }` format.
  version: 2.0.0
servers:
  - url: https://console.cloudblast.io/api/v2
    description: Production
security:
  - bearerAuth: []
paths:
  /sandboxes:
    get:
      tags:
        - Sandboxes
      summary: List sandboxes
      description: >-
        Your sandboxes, newest first: every one that exists, plus failed ones.
        Destroyed sandboxes are not listed. Not paginated.


        `meta.used` is how many slots your sandboxes take, and `meta.max` how
        many your account level allows. `meta.ever_used` is true once the
        account has created a sandbox.


        While sandboxes are switched off on the platform, `data` is empty.
      operationId: listSandboxes
      responses:
        '200':
          description: Your sandboxes
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Sandbox'
                  meta:
                    $ref: '#/components/schemas/SandboxListMeta'
        '401':
          $ref: '#/components/responses/Unauthenticated'
components:
  schemas:
    Sandbox:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
          description: Sandbox handle. Use this as the `{sandbox}` path parameter.
          example: 9b2f4c1e-7d3a-4e8b-a5c6-1f0e2d3c4b5a
        name:
          type: string
          nullable: true
          example: research-agent
        image:
          type: string
          nullable: true
          description: Name of the image it was created from.
          example: Ubuntu 24.04 Desktop
        desktop:
          type: boolean
          description: >-
            True when it was created from a desktop image, so computer use
            works.
          example: true
        status:
          type: string
          description: >-
            `creating`: being created. `running`: ready to use. `stopping`,
            `stopped`, `starting`: on its way down, down with its disk kept, on
            its way up again. `deleting`: being destroyed. `failed`: it could
            not be created, see `error`. `deleted` only shows in the answer to
            an action on a sandbox that is already gone.
          enum:
            - creating
            - running
            - stopping
            - stopped
            - starting
            - deleting
            - deleted
            - failed
          example: running
        os:
          type: string
          enum:
            - linux
            - windows
          example: linux
        vcpu:
          type: integer
          example: 2
        memory_mb:
          type: integer
          example: 4096
        disk_gb:
          type: integer
          example: 20
        private_ip:
          type: string
          nullable: true
          description: Its address on the private sandbox network, once it has one.
          example: 10.80.0.14
        location:
          $ref: '#/components/schemas/SandboxLocation'
        error:
          type: string
          nullable: true
          description: >-
            Why the last create, start or stop did not work. `null` when all is
            well.
          example: null
        hourly_price:
          type: number
          description: Price per hour while it runs.
          example: 0.03
        stopped_hourly_price:
          type: number
          description: 'Price per hour while it is stopped: its disk only.'
          example: 0.002
        current_hourly_price:
          type: number
          description: Price per hour as it is now.
          example: 0.03
        billed_total:
          type: number
          description: Charged so far, billed per minute.
          example: 0.01225
        billed_until:
          type: string
          format: date-time
          nullable: true
          description: Up to when it has been billed.
          example: '2026-11-19T10:15:42+00:00'
        from_pool:
          type: boolean
          description: True when it was handed over already running from the warm pool.
          example: true
        env:
          type: array
          items:
            type: string
          description: >-
            The names of its environment variables. The values are never shown
            again.
          example:
            - API_TOKEN
            - MODE
        auto_stop_minutes:
          type: integer
          description: Minutes without activity before it is stopped. 0 means never.
          example: 15
        auto_destroy_minutes:
          type: integer
          description: >-
            Minutes it may stay stopped before it is destroyed. -1 means never,
            0 means as soon as it stops.
          example: -1
        ephemeral:
          type: boolean
          description: True when it is destroyed as soon as it stops.
          example: false
        created_at:
          type: string
          format: date-time
          example: '2026-11-19T09:58:02+00:00'
        stops_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            When a running sandbox stops if nothing uses it before then. `null`
            when it is not running, or never stops by itself.
          example: '2026-11-19T10:30:42+00:00'
        destroys_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            When a stopped sandbox is destroyed. `null` when it is not stopped,
            or is never destroyed by itself.
          example: null
    SandboxListMeta:
      type: object
      properties:
        ever_used:
          type: boolean
          description: True once the account has created a sandbox.
          example: true
        used:
          type: integer
          description: Slots your sandboxes take now.
          example: 1
        max:
          type: integer
          description: Sandboxes your account level allows at the same time.
          example: 2
    SandboxLocation:
      type: object
      nullable: true
      description: The region a sandbox or an image runs in. `null` when it is not known.
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Frankfurt, Germany
        short_code:
          type: string
          example: fra
        icon:
          type: string
          nullable: true
          description: URL of the location's icon.
          example: https://console.cloudblast.io/storage/locations/de.svg
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code
            message:
              type: string
              description: Human-readable error message
          required:
            - code
            - message
  responses:
    Unauthenticated:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHENTICATED
              message: >-
                Missing or invalid Authorization header. Use: Authorization:
                Bearer <token>
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API token from your CloudBlast account settings. Pass as `Authorization:
        Bearer <token>`.

````

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