---
title: list-sandboxes
product: vercel
url: /docs/rest-api/sandboxes/list-sandboxes
canonical_url: "https://vercel.com/docs/rest-api/sandboxes/list-sandboxes"
last_updated: 2026-10-22
type: reference
prerequisites:
  []
related:
  - /docs/rest-api
summary: Learn about list-sandboxes on Vercel.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

# List sandboxes

```http
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. 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.

## Authentication

**bearerToken**: HTTP bearer

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `project` | string | No | The unique identifier or name of the project to list named sandboxes for. |
| `limit` | number. min: 1; max: 50; default: 20 | No | Maximum number of named sandboxes to return in the response. Used for pagination. |
| `sortBy` | string. enum: createdAt, name, statusUpdatedAt, currentSnapshotId; default: "createdAt" | No | Field to sort by. |
| `namePrefix` | string | No | Filter named sandboxes whose name starts with this prefix. Only valid when sortBy=name. |
| `cursor` | string | No | Opaque pagination cursor from a previous response. |
| `sortOrder` | string. enum: asc, desc; default: "desc" | No | Sort direction. Defaults to desc. |
| `status` | string. enum: running, stopping, stopped | No | Filter named sandboxes by status. Only valid when sortBy is createdAt. |
| `tags` | object | No | Filter sandboxes by tag. Format: \"key:value\". Only one tag filter is supported at a time. |
| `teamId` | string | No | The Team identifier to perform the request on behalf of. |
| `slug` | string | No | The Team slug to perform the request on behalf of. |


## Example request

### TypeScript

```typescript
const response = await fetch('https://api.vercel.com/v2/sandboxes?project=string&limit=123&sortBy=string&namePrefix=string&cursor=string&sortOrder=string&status=string&tags=value&teamId=string&slug=string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);
```

### Next.js

```typescript
'use server';

export async function callEndpoint() {
  const response = await fetch('https://api.vercel.com/v2/sandboxes?project=string&limit=123&sortBy=string&namePrefix=string&cursor=string&sortOrder=string&status=string&tags=value&teamId=string&slug=string', {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${process.env.VERCEL_ACCESS_TOKEN}`,
      'Content-Type': 'application/json',
    },
    next: { revalidate: 3600 }
  });

  if (!response.ok) {
    throw new Error('Request failed');
  }

  return response.json();
}
```

### cURL

```bash
curl -X GET 'https://api.vercel.com/v2/sandboxes?project=string&limit=123&sortBy=string&namePrefix=string&cursor=string&sortOrder=string&status=string&tags=value&teamId=string&slug=string' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json'
```

## Example response

```json
{
  "pagination": {
    "count": "123",
    "next": "string"
  },
  "sandboxes": [
    {
      "architecture": "amd64",
      "createdAt": "1750344501629",
      "currentSessionId": "example_id",
      "currentSnapshotId": "example_id",
      "cwd": "/vercel/sandbox",
      "expiresAt": "1750344801629",
      "failoverRegions": [],
      "image": "my-team/my-project/my-repo@sha256:2c4e8f9a1b3d5e7f091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708",
      "keepLastSnapshots": {
        "count": "5",
        "deleteEvicted": "true",
        "expiration": "604800000"
      },
      "memory": "1024",
      "mounts": "value",
      "name": "my-sandbox",
      "networkId": "example_id",
      "networkPolicy": {
        "allowedCIDRs": [],
        "allowedDomains": [],
        "deniedCIDRs": [],
        "mode": "allow-all",
        "s3Key": "string"
      },
      "persistent": "true",
      "region": "iad1",
      "runtime": "node22",
      "snapshotExpiration": "604800000",
      "status": "running",
      "statusUpdatedAt": "1750344501629",
      "tags": "[object Object]",
      "timeout": "300000",
      "totalActiveCpuDurationMs": "5000",
      "totalDurationMs": "60000",
      "totalEgressBytes": "4096",
      "totalIngressBytes": "2048",
      "updatedAt": "1750344501629",
      "v0": "false",
      "vcpus": "2"
    }
  ]
}
```

## Responses

### 200: No description

Content-Type: `application/json`

```json
{
  "type": "object",
  "required": [
    "pagination",
    "sandboxes"
  ],
  "properties": {
    "pagination": {
      "type": "object",
      "required": [
        "count",
        "next"
      ],
      "properties": {
        "count": {
          "type": "number"
        },
        "next": {
          "type": "string",
          "nullable": true
        }
      }
    },
    "sandboxes": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "This object contains information related to a Vercel NamedSandbox.",
        "required": [
          "createdAt",
          "currentSessionId",
          "name",
          "persistent",
          "status",
          "statusUpdatedAt",
          "updatedAt"
        ],
        "properties": {
          "architecture": {
            "type": "string",
            "description": "CPU architecture of the sandbox. This value does not change.",
            "enum": [
              "amd64",
              "arm64"
            ]
          },
          "createdAt": {
            "type": "number",
            "description": "The time when the named sandbox was created, in milliseconds since the epoch."
          },
          "currentSessionId": {
            "type": "string",
            "description": "Current session ID the sandbox is pointing to."
          },
          "currentSnapshotId": {
            "type": "string",
            "description": "Current snapshot ID that the named sandbox is pointing to."
          },
          "cwd": {
            "type": "string",
            "description": "The working directory of the sandbox."
          },
          "expiresAt": {
            "type": "number",
            "description": "The time at which the currently running sandbox will time out, in milliseconds since the epoch. Only present while a session is running."
          },
          "failoverRegions": {
            "type": "array",
            "description": "The regions the sandbox fails over to. Empty when it does not fail over."
          },
          "image": {
            "type": "string",
            "description": "Owner-qualified, digest-pinned reference of the container image the sandbox was created from (\"{team}/{project}/{repository}@{manifestDigest}\")."
          },
          "keepLastSnapshots": {
            "type": "object",
            "description": "Keep-last snapshot configuration.",
            "required": [
              "count",
              "deleteEvicted"
            ]
          },
          "memory": {
            "type": "number",
            "description": "Memory allocated in MB."
          },
          "mounts": {
            "type": "object",
            "description": "Key-value pairs of mount path and drive."
          },
          "name": {
            "type": "string",
            "description": "The unique identifier of the sandbox."
          },
          "networkId": {
            "type": "string",
            "description": "The Connect network id for the target Secure Compute private network."
          },
          "networkPolicy": {
            "type": "object",
            "description": "Network policy configuration.",
            "required": [
              "mode"
            ]
          },
          "persistent": {
            "type": "boolean",
            "description": "Whether the sandbox persists its state across restarts via automatic snapshots.",
            "enum": [
              false,
              true
            ]
          },
          "region": {
            "type": "string",
            "description": "The region the sandbox is pinned to: the region stored on the sandbox, otherwise the platform default. Where a running session actually landed is reported by `session.region`."
          },
          "runtime": {
            "type": "string",
            "description": "Runtime identifier."
          },
          "snapshotExpiration": {
            "type": "number",
            "description": "Default snapshot expiration time in milliseconds. 0 means no expiration."
          },
          "status": {
            "type": "string",
            "description": "The status of the current sandbox.",
            "enum": [
              "running",
              "stopped",
              "stopping"
            ]
          },
          "statusUpdatedAt": {
            "type": "number",
            "description": "The time when the sandbox status was last updated, in milliseconds since the epoch."
          },
          "tags": {
            "type": "object",
            "description": "Key-value tags attached to the named sandbox."
          },
          "timeout": {
            "type": "number",
            "description": "Timeout in milliseconds."
          },
          "totalActiveCpuDurationMs": {
            "type": "number",
            "description": "Cumulative active CPU duration in milliseconds across all sandbox runs."
          },
          "totalDurationMs": {
            "type": "number",
            "description": "Cumulative wall-clock duration in milliseconds across all sandbox runs."
          },
          "totalEgressBytes": {
            "type": "number",
            "description": "Cumulative egress bytes across all sandbox runs."
          },
          "totalIngressBytes": {
            "type": "number",
            "description": "Cumulative ingress bytes across all sandbox runs."
          },
          "updatedAt": {
            "type": "number",
            "description": "The time when the named sandbox was last updated, in milliseconds since the epoch."
          },
          "v0": {
            "type": "boolean",
            "description": "Whether this sandbox is managed by v0 on the customer's behalf.",
            "enum": [
              false,
              true
            ]
          },
          "vcpus": {
            "type": "number",
            "description": "Number of virtual CPUs allocated."
          }
        }
      }
    }
  }
}
```

### 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: No description

### 410: No description

### 429: No description

---

## Related

- [sandboxes endpoints](/docs/rest-api#sandboxes)

- [REST API overview](/docs/rest-api)

- [OpenAPI spec](https://vercel.com/openapi.json) (machine-readable, all endpoints)

---

[View full sitemap](/docs/sitemap)


If you find anything wrong or missing or can't find something, submit feedback by reading https://vercel.com/feedback.md to improve Vercel.