List sandboxes

List the live Runpod sandboxes owned by the authenticated user, filtered by lifecycle state or by labels. Terminated sandboxes are excluded by default.

GET /v2/sandboxes

cURL

curl --request GET \
  --url "https://api.runpod.io/v2/sandboxes?state=RUNNING&labels=project=quickstart" \
  --header "Authorization: Bearer $RUNPOD_API_KEY"

200

{
  "sandboxes": [
    {
      "id": "7h3sbx91kq",
      "name": "quickstart-sandbox",
      "state": "RUNNING",
      "templateId": null,
      "image": "python:3.12-slim",
      "dataCenterId": "EU-RO-1",
      "compute": {
        "vcpuCount": 2,
        "memoryInGb": 4,
        "containerDiskInGb": 10,
        "costPerHr": 0.08
      },
      "ports": [],
      "egressPolicy": {"mode": "ALLOW_ALL", "allow": []},
      "idleTimeoutSeconds": 300,
      "maxLifetimeSeconds": 3600,
      "lastActivityAt": "2026-10-19T14:02:40Z",
      "idleExpiresAt": "2026-10-19T14:07:40Z",
      "expiresAt": "2026-10-19T15:02:05Z",
      "labels": {"project": "quickstart"},
      "startedAt": "2026-10-19T14:02:09Z",
      "terminationReason": null,
      "terminatedAt": null,
      "createdAt": "2026-10-19T14:02:05Z",
      "updatedAt": "2026-10-19T14:02:40Z"
    }
  ]
}

Returns the authenticated user’s live sandboxes. Terminated sandboxes are excluded unless you set state=TERMINATED. A terminated sandbox stays readable by ID either way. When you pass several filters, a sandbox must match all of them.

Query parameters

state · enum<string>

Only return sandboxes in this lifecycle state. One of CREATING, RUNNING, TERMINATED, or FAILED.

labels · string[]

Only return sandboxes carrying every one of these labels, each written as key=value. Keys and values match exactly, with no wildcard or prefix matching. Repeat the parameter for multiple labels, for example ?labels=project=checkout&labels=env=staging.

Response

sandboxes · Sandbox[] · required

The matching sandboxes. See Get a sandbox for the fields of each sandbox.

Errors

Status	Meaning
401	The API key is missing or invalid.
403	The API key doesn’t have access to sandboxes.
429	Too many requests. Retry after a delay.

cURL

curl --request GET \
  --url "https://api.runpod.io/v2/sandboxes?state=RUNNING&labels=project=quickstart" \
  --header "Authorization: Bearer $RUNPOD_API_KEY"

200

{
  "sandboxes": [
    {
      "id": "7h3sbx91kq",
      "name": "quickstart-sandbox",
      "state": "RUNNING",
      "templateId": null,
      "image": "python:3.12-slim",
      "dataCenterId": "EU-RO-1",
      "compute": {
        "vcpuCount": 2,
        "memoryInGb": 4,
        "containerDiskInGb": 10,
        "costPerHr": 0.08
      },
      "ports": [],
      "egressPolicy": {"mode": "ALLOW_ALL", "allow": []},
      "idleTimeoutSeconds": 300,
      "maxLifetimeSeconds": 3600,
      "lastActivityAt": "2026-10-19T14:02:40Z",
      "idleExpiresAt": "2026-10-19T14:07:40Z",
      "expiresAt": "2026-10-19T15:02:05Z",
      "labels": {"project": "quickstart"},
      "startedAt": "2026-10-19T14:02:09Z",
      "terminationReason": null,
      "terminatedAt": null,
      "createdAt": "2026-10-19T14:02:05Z",
      "updatedAt": "2026-10-19T14:02:40Z"
    }
  ]
}