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

# List sandboxes

> Lists the sandboxes of the workspace, newest first. A deleted sandbox is not in the list. Filter by state, name, start of the name, and label. To find a sandbox by its name, send `name`. To get the next page, send the nextCursor of the last page with the same filters and order. Needs the `sandboxes:read` scope.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/sandboxes
openapi: 3.1.0
info:
  title: VMS API
  version: 1.0.0
  description: >-
    The public API of a VMS workspace. Each request needs an API key of the
    workspace in the Authorization header.
servers:
  - url: https://vms.dev/api
    description: The VMS API
security:
  - apiKey: []
paths:
  /v1/sandboxes:
    get:
      tags:
        - Sandboxes
      summary: List sandboxes
      description: >-
        Lists the sandboxes of the workspace, newest first. A deleted sandbox is
        not in the list. Filter by state, name, start of the name, and label. To
        find a sandbox by its name, send `name`. To get the next page, send the
        nextCursor of the last page with the same filters and order. Needs the
        `sandboxes:read` scope.
      operationId: listSandboxes
      parameters:
        - in: query
          name: limit
          schema:
            default: 50
            type: integer
            minimum: 1
            maximum: 100
        - in: query
          name: cursor
          schema:
            anyOf:
              - type: string
                minLength: 1
                maxLength: 512
              - type: 'null'
        - in: query
          name: state
          schema:
            description: >-
              Return only sandboxes in this state. Send the parameter more than
              one time to give more states.
            type: array
            items:
              $ref: '#/components/schemas/SandboxState'
          description: >-
            Return only sandboxes in this state. Send the parameter more than
            one time to give more states.
        - in: query
          name: name
          schema:
            description: >-
              Return only the sandboxes with this name. Use it to find a sandbox
              by its name.
            type: string
            pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$
            example: agent-42
          description: >-
            Return only the sandboxes with this name. Use it to find a sandbox
            by its name.
        - in: query
          name: namePrefix
          schema:
            description: Return only sandboxes whose name starts with this text.
            example: agent-
            type: string
            pattern: ^[a-z0-9-]{1,63}$
          description: Return only sandboxes whose name starts with this text.
        - in: query
          name: label
          schema:
            description: >-
              Return only sandboxes with this label, as key:value. Send the
              parameter more than one time to give more labels. A sandbox must
              have each label.
            example:
              - project:web
            type: array
            items:
              type: string
              pattern: >-
                ^([A-Za-z0-9](?:[A-Za-z0-9._/-]{0,61}[A-Za-z0-9])?):([\s\S]{0,255})$
          description: >-
            Return only sandboxes with this label, as key:value. Send the
            parameter more than one time to give more labels. A sandbox must
            have each label.
        - in: query
          name: search
          schema:
            description: >-
              Return only sandboxes whose name or ID contains this text. Upper
              and lower case are the same.
            example: agent
            type: string
            minLength: 1
            maxLength: 100
          description: >-
            Return only sandboxes whose name or ID contains this text. Upper and
            lower case are the same.
        - in: query
          name: sort
          schema:
            default: createdAt
            description: >-
              The field to sort by: createdAt (the default), updatedAt, or name.
              A sandbox with no name sorts by its ID.
            type: string
            enum:
              - createdAt
              - updatedAt
              - name
          description: >-
            The field to sort by: createdAt (the default), updatedAt, or name. A
            sandbox with no name sorts by its ID.
        - in: query
          name: order
          schema:
            default: desc
            description: 'The sort order: desc (the default) or asc.'
            type: string
            enum:
              - desc
              - asc
          description: 'The sort order: desc (the default) or asc.'
        - in: query
          name: include
          schema:
            description: >-
              Add fields to the result. cost adds costMicros to each sandbox and
              deletedCostMicros to the page.
            example:
              - cost
            type: array
            items:
              type: string
              enum:
                - cost
          description: >-
            Add fields to the result. cost adds costMicros to each sandbox and
            deletedCostMicros to the page.
      responses:
        '200':
          description: One page of sandboxes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxPage'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, not correct, revoked, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The API key does not have the scope of the endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: The API key sent more than 1,200 requests in one minute.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SandboxState:
      type: string
      enum:
        - creating
        - starting
        - running
        - stopping
        - stopped
        - error
        - deleting
        - deleted
        - failed
    SandboxPage:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Sandbox'
        nextCursor:
          type:
            - string
            - 'null'
        deletedCostMicros:
          description: >-
            The cost of the deleted sandboxes in the current month (UTC), in
            micro-dollars. Only with include=cost.
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - data
        - nextCursor
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: no_capacity
            message:
              type: string
            requestId:
              type:
                - string
                - 'null'
            retryAfterSeconds:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            sandboxId:
              description: The sandbox that the error is about.
              type: string
          required:
            - code
            - message
            - requestId
          additionalProperties: false
      required:
        - error
      additionalProperties: false
    Sandbox:
      type: object
      properties:
        id:
          type: string
          example: sbx_06d8k3m7q2v9x4b1n5c0e8f2ja
        name:
          type:
            - string
            - 'null'
        state:
          $ref: '#/components/schemas/SandboxState'
        size:
          $ref: '#/components/schemas/SandboxSize'
        health:
          anyOf:
            - $ref: '#/components/schemas/SandboxHealth'
            - type: 'null'
          description: Null when the sandbox is not running.
        errorReason:
          anyOf:
            - $ref: '#/components/schemas/SandboxErrorReason'
            - type: 'null'
          description: Why the sandbox is in the error state.
        labels:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: string
        ipv6:
          example: 2604:2dc0:100:32d5::1a
          type:
            - string
            - 'null'
        urls:
          type: array
          items:
            $ref: '#/components/schemas/SandboxUrl'
        sshHostKey:
          description: The public SSH host key of the sandbox.
          type:
            - string
            - 'null'
        sshUser:
          type: string
          description: >-
            The user name for ssh.vms.dev: the name and the workspace code, or
            the sandbox ID when the sandbox has no name.
          example: agent-42-k3m7q2v9
        stopAt:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            - type: 'null'
          description: >-
            When the sandbox stops on its own. Null when auto-stop is off or the
            sandbox does not run.
        stopAfterSeconds:
          anyOf:
            - type: integer
              exclusiveMinimum: 0
              maximum: 9007199254740991
            - type: 'null'
          description: >-
            The seconds that the sandbox runs after each start before it stops
            on its own. Null when auto-stop is off.
          example: 3600
        dataExpiresAt:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            - type: 'null'
          description: >-
            When the saved files are deleted: 30 days after a stop, or at a
            delete. Null while the sandbox runs.
        latestSnapshotAt:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            - type: 'null'
        snapshotVerifiedAt:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            - type: 'null'
        lastSnapshotLagSeconds:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 9007199254740991
            - type: 'null'
        snapshotProgress:
          anyOf:
            - type: number
              minimum: 0
              maximum: 1
            - type: 'null'
          description: The part of the current snapshot that is done, 0 to 1.
        hydrated:
          type: boolean
          description: >-
            true when each saved file is on the local disk. After a resume from
            saved files, the sandbox is running before this is true: a file that
            is not local yet downloads when a program opens it.
        hydratedAt:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            - type: 'null'
          description: >-
            When the last restore put each saved file on the local disk. Null
            when the sandbox did not restore saved files.
        hydration:
          $ref: '#/components/schemas/SandboxHydration'
        lastReboot:
          anyOf:
            - $ref: '#/components/schemas/SandboxLastReboot'
            - type: 'null'
        operation:
          anyOf:
            - $ref: '#/components/schemas/Operation'
            - type: 'null'
          description: The latest operation on the sandbox.
        costMicros:
          description: >-
            The cost of the sandbox in the current month (UTC), in
            micro-dollars: 1,000,000 is $1. Only in a list with include=cost.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        forkedFrom:
          description: >-
            The ID of the sandbox that this sandbox is a fork of. Null when it
            is not a fork.
          example: sbx_06d8k3m7q2v9x4b1n5c0e8f2ja
          type:
            - string
            - 'null'
        imageVersion:
          description: >-
            The version of the base image of the sandbox. Null before the first
            start.
          example: ubuntu-26.04-20261116130819
          type:
            - string
            - 'null'
        pinImage:
          type: boolean
          description: >-
            true when a resume keeps the current base image. false when a resume
            after the 10-minute hold moves the sandbox to the latest base image.
        createdAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
        updatedAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
      required:
        - id
        - name
        - state
        - size
        - health
        - errorReason
        - labels
        - ipv6
        - urls
        - sshHostKey
        - sshUser
        - stopAt
        - stopAfterSeconds
        - dataExpiresAt
        - latestSnapshotAt
        - snapshotVerifiedAt
        - lastSnapshotLagSeconds
        - snapshotProgress
        - hydrated
        - hydratedAt
        - hydration
        - lastReboot
        - operation
        - forkedFrom
        - imageVersion
        - pinImage
        - createdAt
        - updatedAt
      additionalProperties: false
    SandboxSize:
      type: string
      enum:
        - small
        - medium
        - large
        - xlarge
      description: The vCPU, RAM, and disk of a sandbox.
    SandboxHealth:
      type: string
      enum:
        - ok
        - degraded
        - unreachable
    SandboxErrorReason:
      type: string
      enum:
        - host_lost
        - boot_failed
        - restore_failed
    SandboxUrl:
      type: object
      properties:
        id:
          type: string
          example: url_06d8k3m7q2v9x4b1n5c0e8f2jb
        sandboxId:
          type: string
          example: sbx_06d8k3m7q2v9x4b1n5c0e8f2ja
        port:
          type: integer
          minimum: 1
          maximum: 65535
          example: 3000
        url:
          type: string
          format: uri
          description: >-
            The HTTPS address of the port. It contains the sandbox name, so it
            changes when you rename the sandbox.
          example: https://agent-42-3000-k3m7q2v9.vmsdev.run
        public:
          type: boolean
          description: True if the URL works without the token.
        token:
          description: >-
            Open the URL one time with ?_token=<token>. The browser then keeps a
            cookie for the URL. It is null for an API key without
            sandboxes:write.
          example: vmsu_Gq3n0Yb1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t
          type:
            - string
            - 'null'
        createdAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
        updatedAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
      required:
        - id
        - sandboxId
        - port
        - url
        - public
        - token
        - createdAt
        - updatedAt
      additionalProperties: false
    SandboxHydration:
      type: object
      properties:
        phase:
          $ref: '#/components/schemas/HydrationPhase'
        filesDone:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: The files of the home folders that are on the local disk.
        filesTotal:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: The files of the home folders that the restore puts back.
        errorCode:
          anyOf:
            - type: string
              enum:
                - hydration_failed
            - type: 'null'
          description: >-
            hydration_failed when the phase is failed: the download stopped for
            good. Null in each other phase.
      required:
        - phase
        - filesDone
        - filesTotal
        - errorCode
      additionalProperties: false
      description: The progress of the last restore of saved files.
    SandboxLastReboot:
      type: object
      properties:
        reason:
          $ref: '#/components/schemas/RebootReason'
        at:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
      required:
        - reason
        - at
      additionalProperties: false
    Operation:
      type: object
      properties:
        id:
          type: string
          example: op_06d8k3m7q2v9x4b1n5c0e8f2ja
        sandboxId:
          type: string
          example: sbx_06d8k3m7q2v9x4b1n5c0e8f2ja
        kind:
          $ref: '#/components/schemas/OperationKind'
        status:
          $ref: '#/components/schemas/OperationStatus'
        error:
          anyOf:
            - $ref: '#/components/schemas/OperationError'
            - type: 'null'
        createdAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
        updatedAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
        completedAt:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            - type: 'null'
      required:
        - id
        - sandboxId
        - kind
        - status
        - error
        - createdAt
        - updatedAt
        - completedAt
      additionalProperties: false
    HydrationPhase:
      type: string
      enum:
        - folding
        - system
        - docker
        - hydrating
        - hydrated
        - failed
      description: >-
        The step of the restore: folding reads the saved snapshots, system puts
        back the system files, docker puts back the Docker files and starts the
        services, hydrating downloads the files of the home folders, hydrated
        means that each saved file is on the local disk, and failed means that
        the download stopped for good after its tries.
    RebootReason:
      type: string
      enum:
        - crash
        - guest
    OperationKind:
      type: string
      enum:
        - create
        - stop
        - resume
        - delete
        - recover
    OperationStatus:
      type: string
      enum:
        - pending
        - running
        - failing
        - succeeded
        - failed
    OperationError:
      type: object
      properties:
        code:
          type: string
          example: no_capacity
        message:
          type: string
      required:
        - code
        - message
      additionalProperties: false
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: An API key that starts with vms_. Make one in Settings > API keys.

````

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