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

# List sandboxes created by this API access grant



## OpenAPI

````yaml /openapi.json get /api/public/v1/sandboxes
openapi: 3.1.0
info:
  title: Sparkles Sandbox API
  version: 1.0.0
  description: Create coding sandboxes, stream their work, and control their lifecycle.
servers:
  - url: https://sparkles.dev
security: []
paths:
  /api/public/v1/sandboxes:
    get:
      tags:
        - sandboxes
      summary: List sandboxes created by this API access grant
      operationId: listSandboxes
      parameters:
        - in: query
          name: after
          schema:
            type: string
            minLength: 1
            maxLength: 1000
        - in: query
          name: limit
          schema:
            default: 100
            type: integer
            minimum: 1
            maximum: 100
        - in: query
          name: status
          schema:
            type: string
            enum:
              - queued
              - creating
              - running
              - succeeded
              - failed
              - terminating
              - terminated
        - in: query
          name: repo
          schema:
            type: string
            maxLength: 201
            pattern: ^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$
      responses:
        '200':
          description: Grant-scoped sandboxes in newest-first order
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          pattern: ^c_[a-z2-9]{12}$
                        worktreeId:
                          readOnly: true
                          type: string
                          minLength: 1
                        object:
                          type: string
                          const: sandbox
                        status:
                          type: string
                          enum:
                            - queued
                            - creating
                            - running
                            - succeeded
                            - failed
                            - terminating
                            - terminated
                        title:
                          type: string
                        repos:
                          type: array
                          items:
                            type: object
                            properties:
                              fullName:
                                type: string
                                maxLength: 201
                                pattern: ^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$
                              ref:
                                type: string
                                minLength: 1
                                maxLength: 255
                            required:
                              - fullName
                            additionalProperties: false
                        model:
                          type:
                            - string
                            - 'null'
                        agentRuntime:
                          type: string
                          enum:
                            - opencode
                            - codex
                            - claude
                            - grok
                        turn:
                          type: object
                          properties:
                            active:
                              type: boolean
                          required:
                            - active
                          additionalProperties: false
                        usage:
                          type: object
                          properties:
                            llmRequestCount:
                              type: integer
                              minimum: 0
                              maximum: 9007199254740991
                            costMicroUsd:
                              type: integer
                              minimum: 0
                              maximum: 9007199254740991
                            creditsChargedMicros:
                              type: integer
                              minimum: 0
                              maximum: 9007199254740991
                          required:
                            - llmRequestCount
                            - costMicroUsd
                            - creditsChargedMicros
                          additionalProperties: false
                        metadata:
                          type: object
                          propertyNames:
                            type: string
                          additionalProperties:
                            type: string
                        error:
                          type:
                            - string
                            - 'null'
                        createdAt:
                          type: string
                        startedAt:
                          type:
                            - string
                            - 'null'
                        completedAt:
                          type:
                            - string
                            - 'null'
                        links:
                          type: object
                          properties:
                            self:
                              type: string
                              format: uri
                            events:
                              type: string
                              format: uri
                            messages:
                              type: string
                              format: uri
                          required:
                            - self
                            - events
                            - messages
                          additionalProperties: false
                      required:
                        - id
                        - worktreeId
                        - object
                        - status
                        - title
                        - repos
                        - model
                        - agentRuntime
                        - turn
                        - usage
                        - metadata
                        - error
                        - createdAt
                        - startedAt
                        - completedAt
                        - links
                      additionalProperties: false
                  nextCursor:
                    type:
                      - string
                      - 'null'
                required:
                  - data
                  - nextCursor
                additionalProperties: false
        '400':
          description: List filters or cursor failed validation
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '401':
          description: Missing, malformed, revoked, or otherwise invalid API key
          headers:
            WWW-Authenticate:
              required: true
              description: Bearer authentication challenge for the Sparkles Sandbox API
              schema:
                type: string
                description: Bearer authentication challenge for the Sparkles Sandbox API
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '403':
          description: >-
            The API key lacks the sandboxes scope or its user is no longer an
            active organization member
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '429':
          description: The API key exceeded its distributed per-minute request limit
          headers:
            Retry-After:
              required: true
              description: Seconds until another request may be made
              schema:
                type: string
                pattern: ^\d+$
                description: Seconds until another request may be made
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '500':
          description: The request could not be completed because of an internal error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: spk_live_…
      description: >-
        Long-lived opaque API key minted by an approved user at /api. The secret
        is shown once, stored only as a SHA-256 digest, and disabled immediately
        when either the key or its API access grant is revoked.

````