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

# List Sandboxes

> List all sandboxes associated with the authenticated account and their current statuses. Returns sandbox details including lifecycle state, timeout remaining, and creation timestamp. Pass account_id to retrieve sandboxes for a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.



## OpenAPI

````yaml api-reference/openapi/content.json GET /api/sandboxes
openapi: 3.1.0
info:
  title: Recoup API - Content
  description: >-
    API documentation for the Recoup platform - an AI agent platform for the
    music industry
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.recoupable.dev
security: []
paths:
  /api/sandboxes:
    get:
      description: >-
        List all sandboxes associated with the authenticated account and their
        current statuses. Returns sandbox details including lifecycle state,
        timeout remaining, and creation timestamp. Pass account_id to retrieve
        sandboxes for a specific account the API key has access to.
        Authentication is handled via the x-api-key header or Authorization
        Bearer token.
      parameters:
        - name: sandbox_id
          in: query
          required: false
          description: >-
            Filter by a specific sandbox ID. When provided, returns only the
            sandbox matching this ID. Must be a sandbox that your account or
            organization is an admin of.
          schema:
            type: string
            example: sbx_abc123def456
        - name: account_id
          in: query
          description: >-
            Filter to a specific account. Only applicable when the authenticated
            account has access to multiple accounts via organization membership.
          required: false
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Sandboxes retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxesResponse'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxErrorResponse'
        '403':
          description: >-
            Forbidden - account_id is not a member of the organization or
            account tried to filter by an account_id they don't have access to
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxErrorResponse'
components:
  schemas:
    SandboxesResponse:
      type: object
      required:
        - status
        - sandboxes
      description: Response containing sandbox information
      properties:
        status:
          type: string
          enum:
            - success
            - error
          description: Status of the request
        sandboxes:
          type: array
          items:
            $ref: '#/components/schemas/Sandbox'
          description: Array of sandbox objects
        snapshot_id:
          type: string
          description: >-
            The account's saved snapshot ID used for creating new sandboxes.
            Null if no snapshot has been saved.
          example: snap_abc123def456
          nullable: true
        github_repo:
          type: string
          description: >-
            The GitHub repository URL associated with the account's sandbox
            environment. Used as the filesystem source when restoring sandboxes.
          example: https://github.com/username/repo
          nullable: true
        filetree:
          type: array
          nullable: true
          description: >-
            The recursive file tree of the account's GitHub repository. Null if
            no github_repo is set or if the fetch fails.
          items:
            $ref: '#/components/schemas/FileTreeEntry'
        error:
          type: string
          description: Error message (only present if status is error)
    SandboxErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
          example: Failed to create sandbox
    Sandbox:
      type: object
      required:
        - sandboxId
        - sandboxStatus
        - timeout
        - createdAt
      description: A sandbox environment instance
      properties:
        sandboxId:
          type: string
          description: Unique identifier for the sandbox
          example: sbx_abc123def456
        sandboxStatus:
          type: string
          enum:
            - pending
            - running
            - stopping
            - stopped
            - failed
          description: Current lifecycle state of the sandbox
          example: running
        timeout:
          type: integer
          description: Milliseconds remaining before the sandbox stops automatically
          example: 300000
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the sandbox was created
          example: '2024-01-15T10:30:00.000Z'
        runId:
          type: string
          description: >-
            Unique identifier for the command execution run. Only present if a
            command was provided when creating the sandbox. Use this with [GET
            /api/tasks/runs](/api-reference/tasks/runs) to check the status and
            retrieve results.
          example: run_xyz789abc123
    FileTreeEntry:
      type: object
      required:
        - path
        - type
        - sha
      description: A single entry in a GitHub repository file tree
      properties:
        path:
          type: string
          description: The file or directory path relative to the repository root
          example: src/index.ts
        type:
          type: string
          enum:
            - blob
            - tree
          description: 'The type of entry: blob for files, tree for directories'
        sha:
          type: string
          description: The SHA hash of the entry
          example: abc123def456
        size:
          type: integer
          description: The size of the file in bytes. Only present for blob entries.
          example: 1024

````