> ## 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.

# Get the current sandbox state



## OpenAPI

````yaml /openapi.json get /api/public/v1/sandboxes/{sandboxId}
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/{sandboxId}:
    get:
      tags:
        - sandboxes
      summary: Get the current sandbox state
      operationId: getSandbox
      parameters:
        - in: path
          name: sandboxId
          schema:
            type: string
            pattern: ^c_[a-z2-9]{12}$
          required: true
      responses:
        '200':
          description: Current sandbox state and eventually consistent usage
          content:
            application/json:
              schema:
                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
        '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
        '404':
          description: Sandbox not found for this API access grant
          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.

````