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.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

API keyx-api-key header

Kept in this browser tab only and cleared when it closes.

sandbox_idquery · string

account_idquery · string

cURL for this request

curl --request GET \
  --url 'https://recoup-api.vercel.app/api/sandboxes'

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