Reference / Agent Sandboxes

List sandboxes

List your workspace's sandboxes, newest first, with offered sizes and the running limit.

GET/v1/customer/tenants/{tenantId}/sandboxes

Base URL: https://api.runzivo.dev

Authentication

Send Authorization: Bearer <token> with a customer access token or workspace API key.

API key permission: sandboxes:read or sandboxes:write. These are permissions, not legacy scopes. A key with the all:all scope also works, limited by its creator's current workspace permissions.

Parameters

Path and query parameters
Field	Description
`tenantId`string · pathRequired	Your workspace's tenant ID. Replace the placeholder with an ID your token can access.

Request body

No request body is required.

Behavior and limits

No pagination or query parameters. The response contains sandboxes, sizes and max_running as siblings, not a nested data or items envelope.
Use the sizes returned for this environment when creating a sandbox. A size being offered does not guarantee immediate free capacity.

Responses

HTTP response codes
Status	Meaning
200 OK	application/json
401 Unauthorized	Missing or invalid bearer token. A ticketed terminal request can instead return ticket_invalid.
403 Forbidden	The caller lacks workspace membership or permission, or the API key is not allowed. Codes include tenant_membership_required, permission_required and api_key_scope_required.
500 Internal error	The server could not complete the request.
503 Unavailable	Sandbox service is unavailable. Exec and terminal operations can also return sandbox_exec_unavailable.

Examples use synthetic IDs, dates and values. Read the actual response and status in your workspace.

Sandbox response fields

The list response has sandboxes (an array of the objects below), sizes (offered size IDs) and max_running (the workspace running limit).

Sandbox object
Field	Description
`id`stringRequired	Sandbox ID: sbx_ followed by 24 lowercase hexadecimal characters.
`name`stringRequired	Workspace sandbox name.
`size`stringRequired	The selected size identifier.
`disk_gib`integerRequired	Workspace disk size in GiB.
`status`stringRequired	pending, starting, running, stopping, stopped, deleting, deleted, expired or failed.
`error`object \| nullRequired	null, or {code, message} explaining a failed sandbox.
`created_at`date-timeRequired	When the sandbox was created.
`started_at`date-time \| nullRequired	First start; null until it starts.
`expires_at`date-time \| nullRequired	First start plus eight hours. Stopping does not pause the lifetime.
`remaining_seconds`integerRequired	Lifetime left; 28800 before first start, 0 once expired or deleted.
`runtime_seconds`integerRequired	Seconds the VM has been up; excludes stopped time.
`credits_used`numberRequired	Unit-minutes charged at the size's multiplier.

Sandbox limits and billing →

Page tools

View as Markdown

Ask AI about this page

Open in ChatGPT Open in Claude Open in Cursor

Claude shows a caution banner on any prefilled prompt. That is expected: review the prompt, then send it.

Request example

Illustrative request. Set RUNZIVO_TOKEN and TENANT_ID in your shell. Replace placeholders with your own values. This page does not send requests.

cURL

curl --request GET \
  "https://api.runzivo.dev/v1/customer/tenants/${TENANT_ID}/sandboxes" \
  --header "Authorization: Bearer ${RUNZIVO_TOKEN}"

Response example

application/json · Illustrative response; values and timing vary in your workspace.

200 · application/json

{
  "sandboxes": [
    {
      "id": "sbx_000000000000000000000001",
      "name": "docs-example",
      "size": "2vcpu-8gb",
      "disk_gib": 20,
      "status": "running",
      "error": null,
      "created_at": "2026-10-31T12:00:00Z",
      "started_at": "2026-10-31T12:00:00Z",
      "expires_at": "2026-10-31T20:00:00Z",
      "remaining_seconds": 28740,
      "runtime_seconds": 60,
      "credits_used": 1
    }
  ],
  "max_running": 2,
  "sizes": [
    "2vcpu-8gb",
    "4vcpu-16gb"
  ]
}

All response examples (also available without JavaScript)

200 OK

Illustrative response; values and timing vary in your workspace.

application/json

{
  "sandboxes": [
    {
      "id": "sbx_000000000000000000000001",
      "name": "docs-example",
      "size": "2vcpu-8gb",
      "disk_gib": 20,
      "status": "running",
      "error": null,
      "created_at": "2026-10-31T12:00:00Z",
      "started_at": "2026-10-31T12:00:00Z",
      "expires_at": "2026-10-31T20:00:00Z",
      "remaining_seconds": 28740,
      "runtime_seconds": 60,
      "credits_used": 1
    }
  ],
  "max_running": 2,
  "sizes": [
    "2vcpu-8gb",
    "4vcpu-16gb"
  ]
}

401 Unauthorized

Missing or invalid bearer token. A ticketed terminal request can instead return ticket_invalid.

application/json

{
  "error": {
    "code": "unauthorized"
  }
}

403 Forbidden

The caller lacks workspace membership or permission, or the API key is not allowed. Codes include tenant_membership_required, permission_required and api_key_scope_required.

application/json

{
  "error": {
    "code": "permission_required"
  }
}

500 Internal error

The server could not complete the request.

application/json

{
  "error": {
    "code": "internal_error"
  }
}

503 Unavailable

Sandbox service is unavailable. Exec and terminal operations can also return sandbox_exec_unavailable.

application/json

{
  "error": {
    "code": "sandboxes_unavailable"
  }
}