sandboxes

List sandboxes

Changed on

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. Overdue sessions for running and stopping sandboxes are recovered before returning the page, so an entry may no longer match its queried status after recovery.

get/v2/sandboxes

Request

  • Base URL: https://api.vercel.com
  • URL: https://api.vercel.com/v2/sandboxes
  • Auth: HTTP bearer

Query parameters

projectstring

The unique identifier or name of the project to list named sandboxes for.

Example:prj_abc123
limitnumber

Maximum number of named sandboxes to return in the response. Used for pagination.

Example:20
sortBy'createdAt' | 'name' | 'statusUpdatedAt' | 'currentSnapshotId'

Field to sort by.

namePrefixstring

Filter named sandboxes whose name starts with this prefix. Only valid when sortBy=name.

cursorstring

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.

string
OR
string[]
teamIdstring
Example:team_1a2b3c4d5e6f7g8h9i0j1k2l

The Team identifier to perform the request on behalf of.

slugstring
Example:my-team-url-slug

The Team slug to perform the request on behalf of.

Response

Example response

{
  "sandboxes": [
    {
      "createdAt": 1750344501629,
      "cwd": "/vercel/sandbox",
      "expiresAt": 1750344801629,
      "failoverRegions": [
        "sfo1",
        "cle1"
      ],
      "image": "my-team/my-project/my-repo@sha256:2c4e8f9a1b3d5e7f091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708",
      "keepLastSnapshots": {
        "count": 5,
        "deleteEvicted": true,
        "expiration": 604800000
      },
      "memory": 1024,
      "name": "my-sandbox",
      "persistent": true,
      "region": "iad1",
      "runtime": "node22",
      "snapshotExpiration": 604800000,
      "status": "running",
      "statusUpdatedAt": 1750344501629,
      "tags": {
        "team": "hive",
        "user": "bob"
      },
      "timeout": 300000,
      "totalActiveCpuDurationMs": 5000,
      "totalDurationMs": 60000,
      "totalEgressBytes": 4096,
      "totalIngressBytes": 2048,
      "updatedAt": 1750344501629,
      "vcpus": 2
    }
  ]
}

Changes