---
title: "List sandboxes"
method: GET
path: "/v2/sandboxes"
tags: ["sandboxes"]
---

# List sandboxes

`GET /v2/sandboxes`

Retrieves a paginated list of named sandboxes belonging to a specific project. Results can be sorted by creation time or name, and optionally filtered by name prefix or status.

## Query parameters

- `project` string — The unique identifier or name of the project to list named sandboxes for.
- `limit` number — Maximum number of named sandboxes to return in the response. Used for pagination.
- `sortBy` 'createdAt' | 'name' | 'statusUpdatedAt' | 'currentSnapshotId' — Field to sort by.
- `namePrefix` string — Filter named sandboxes whose name starts with this prefix. Only valid when sortBy=name.
- `cursor` string — Opaque pagination cursor from a previous response.
- `sortOrder` 'asc' | 'desc' — Sort direction. Defaults to desc.
- `status` 'running' | 'stopping' | 'stopped' — Filter named sandboxes by status. Only valid when sortBy is createdAt.
- `tags` union — Filter sandboxes by tag. Format: \"key:value\". Only one tag filter is supported at a time.
  - string
  - string[]
- `teamId` string
- `slug` string

## Response `200`

- object
  - `sandboxes` NamedSandbox[], required
    - `name` string, required — The unique identifier of the sandbox.
    - `currentSnapshotId` string — Current snapshot ID that the named sandbox is pointing to.
    - `currentSessionId` string, required — Current session ID the sandbox is pointing to.
    - `status` 'running' | 'stopped' | 'stopping', required — The status of the current sandbox.
    - `statusUpdatedAt` number, required — The time when the sandbox status was last updated, in milliseconds since the epoch.
    - `persistent` false | true, required — Whether the sandbox persists its state across restarts via automatic snapshots.
    - `region` string — The region the sandbox is configured to run in: the region set on the sandbox, otherwise the project-level default, then the platform default. Where a running session actually landed is reported by `session.region`.
    - `vcpus` number — Number of virtual CPUs allocated.
    - `memory` number — Memory allocated in MB.
    - `runtime` string — Runtime identifier.
    - `image` string — Digest-pinned reference of the container image the sandbox was created from, when it was created from an image ("{repository}@{manifestDigest}").
    - `timeout` number — Timeout in milliseconds.
    - `snapshotExpiration` number — Default snapshot expiration time in milliseconds. 0 means no expiration.
    - `keepLastSnapshots` object — Keep-last snapshot configuration.
      - `count` number, required — Number of most recent snapshots to keep.
      - `expiration` number — Expiration time in milliseconds for kept snapshots.
      - `deleteEvicted` false | true, required — Whether to immediately delete evicted snapshots.
    - `networkPolicy` object — Network policy configuration.
      - `mode` 'allow-all' | 'custom' | 'default-allow' | 'default-deny' | 'deny-all', required
      - `allowedDomains` string[]
      - `allowedCIDRs` string[]
      - `deniedCIDRs` string[]
    - `totalEgressBytes` number — Cumulative egress bytes across all sandbox runs.
    - `totalIngressBytes` number — Cumulative ingress bytes across all sandbox runs.
    - `totalActiveCpuDurationMs` number — Cumulative active CPU duration in milliseconds across all sandbox runs.
    - `totalDurationMs` number — Cumulative wall-clock duration in milliseconds across all sandbox runs.
    - `cwd` string — The working directory of the sandbox.
    - `tags` object — Key-value tags attached to the named sandbox.
    - `mounts` object — Key-value pairs of mount path and drive.
    - `createdAt` number, required — The time when the named sandbox was created, in milliseconds since the epoch.
    - `updatedAt` number, required — The time when the named sandbox was last updated, in milliseconds since the epoch.
    - `expiresAt` number — The time at which the currently running sandbox will time out, in milliseconds since the epoch. Only present while a session is running.
  - `pagination` object, required
    - `count` number, required
    - `next` string, nullable, required

## Other responses

- `400` — One of the provided values in the request query is invalid.
- `401` — The request is not authorized.
- `403` — You do not have permission to access this resource.
- `404`
- `410`
- `429`

---

[API](https://skmtc.net/vercel/apis/api.md) · [All operations](https://skmtc.net/vercel/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vercel/api/versions/61d1ba3f6dac/schema)