# List Sandboxes

Source: https://recoupable.dev/docs/api-reference/sandboxes/list

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.

## GET /api/sandboxes

Full OpenAPI specification: https://recoupable.dev/docs/spec/content.json

## Authentication

The supplied specification does not declare an OpenAPI security object for this operation. Its declared headers and parameters still apply. Consult the authentication guide and the full specification before calling it.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "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"
    }
  ],
  "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
          }
        }
      }
    }
  }
}
```