# 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 ` 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 | Field | Description | | --- | --- | | `tenantId` string · path Required | 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 | 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). | Field | Description | | --- | --- | | `id` string Required | Sandbox ID: sbx\_ followed by 24 lowercase hexadecimal characters. | | `name` string Required | Workspace sandbox name. | | `size` string Required | The selected size identifier. | | `disk_gib` integer Required | Workspace disk size in GiB. | | `status` string Required | pending, starting, running, stopping, stopped, deleting, deleted, expired or failed. | | `error` object \| null Required | null, or {code, message} explaining a failed sandbox. | | `created_at` date-time Required | When the sandbox was created. | | `started_at` date-time \| null Required | First start; null until it starts. | | `expires_at` date-time \| null Required | First start plus eight hours. Stopping does not pause the lifetime. | | `remaining_seconds` integer Required | Lifetime left; 28800 before first start, 0 once expired or deleted. | | `runtime_seconds` integer Required | Seconds the VM has been up; excludes stopped time. | | `credits_used` number Required | Unit-minutes charged at the size's multiplier. | [Sandbox limits and billing](https://runzivo.dev/docs/sandboxes-limits/) Page tools [View as Markdown](https://runzivo.dev/docs/reference/sandboxes/list.md) Ask AI about this page [Open in ChatGPT](https://chatgpt.com/?q=Read%20this%20Runzivo%20documentation%20page%2C%20then%20help%20me%20with%20it%3A%0A%0Ahttps%3A%2F%2Frunzivo.dev%2Fdocs%2Freference%2Fsandboxes%2Flist.md) [Open in Claude](https://claude.ai/new?q=Read%20this%20Runzivo%20documentation%20page%2C%20then%20help%20me%20with%20it%3A%0A%0Ahttps%3A%2F%2Frunzivo.dev%2Fdocs%2Freference%2Fsandboxes%2Flist.md) [Open in Cursor](https://cursor.com/link/prompt?text=Read%20this%20Runzivo%20documentation%20page%2C%20then%20help%20me%20with%20it%3A%0A%0Ahttps%3A%2F%2Frunzivo.dev%2Fdocs%2Freference%2Fsandboxes%2Flist.md) 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" } } ```