API REFERENCE

List Sandboxes

On this page

GET/api/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.

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/sandboxes' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Query parameters

sandbox_idstring

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.

account_idstring

Filter to a specific account. Only applicable when the authenticated account has access to multiple accounts via organization membership.

Responses

200Sandboxes retrieved successfully

application/json

statusstring · enumrequired

Status of the request

Values: "success", "error"

sandboxesarray<Sandbox>required

Array of sandbox objects

Item properties

sandboxIdstringrequired

Unique identifier for the sandbox

sandboxStatusstring · enumrequired

Current lifecycle state of the sandbox

Values: "pending", "running", "stopping", "stopped", "failed"

timeoutintegerrequired

Milliseconds remaining before the sandbox stops automatically

createdAtstringrequired

ISO 8601 timestamp when the sandbox was created

format: date-time

runIdstring

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 to check the status and retrieve results.

snapshot_idstringnullable

The account's saved snapshot ID used for creating new sandboxes. Null if no snapshot has been saved.

github_repostringnullable

The GitHub repository URL associated with the account's sandbox environment. Used as the filesystem source when restoring sandboxes.

filetreearray<FileTreeEntry>nullable

The recursive file tree of the account's GitHub repository. Null if no github_repo is set or if the fetch fails.

Item properties

pathstringrequired

The file or directory path relative to the repository root

typestring · enumrequired

The type of entry: blob for files, tree for directories

Values: "blob", "tree"

shastringrequired

The SHA hash of the entry

sizeinteger

The size of the file in bytes. Only present for blob entries.

errorstring

Error message (only present if status is error)

401Unauthorized - invalid or missing API key

application/json

errorstringrequired

Error message describing what went wrong

403Forbidden - account_id is not a member of the organization or account tried to filter by an account_id they don't have access to

application/json

errorstringrequired

Error message describing what went wrong

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download content.json

View operation source

json

{
  "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"
          }
        }
      }
    }
  }
}