--- title: list-sessions product: vercel url: /docs/rest-api/sandboxes-v2-beta/list-sessions type: reference prerequisites: [] related: - /docs/rest-api summary: Learn about list-sessions on Vercel. install_vercel_plugin: npx plugins add vercel/vercel-plugin --- # List sessions ```http GET /v2/sandboxes/sessions ``` Retrieves a paginated list of sessions belonging to a specific sandbox. Results are sorted by creation time and paginated using an opaque cursor. ## Authentication **bearerToken**: HTTP bearer ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `project` | string | No | The unique identifier or name of the project to list sessions for. | | `name` | string. maxLength: 128; pattern: `^[a-zA-Z0-9_-]+$` | No | Filter sessions by sandbox name. Only sessions belonging to the specified sandbox are returned. | | `limit` | number. min: 1; max: 50; default: 20 | No | Maximum number of sessions to return in the response. Used for pagination. | | `cursor` | string | No | Opaque pagination cursor from a previous response. | | `sortOrder` | string. enum: asc, desc; default: "desc" | No | Sort direction for results by creation 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. | ## Responses ### 200: The list of sessions matching the request filters. Content-Type: `application/json` ```json { "oneOf": [ { "type": "object" }, { "type": "object", "required": [ "pagination", "sessions" ], "properties": { "sessions": { "type": "array", "items": { "type": "object", "description": "This object contains information related to a Vercel Sandbox Session. v2 endpoints return \"session\" instead of \"sandbox\" as the response wrapper key.", "required": [ "createdAt", "cwd", "id", "memory", "projectId", "region", "requestedAt", "runtime", "sourceSandboxName", "status", "timeout", "updatedAt", "vcpus" ], "properties": { "sourceSandboxName": { "type": "string", "description": "The name of the source sandbox." }, "projectId": { "type": "string", "description": "The unique identifier of the project associated with this session." }, "id": { "type": "string", "description": "The unique identifier of the sandbox." }, "memory": { "type": "number", "description": "Memory allocated to this sandbox in MB." }, "vcpus": { "type": "number", "description": "Number of vCPUs allocated to this sandbox." }, "region": { "type": "string", "description": "The region where the sandbox is hosted." }, "runtime": { "type": "string", "description": "The runtime of the sandbox." }, "timeout": { "type": "number", "description": "The maximum amount of time the sandbox will run for in milliseconds." }, "status": { "type": "string", "description": "The status of the sandbox.", "enum": [ "failed", "aborted", "pending", "stopping", "snapshotting", "running", "stopped" ] }, "requestedAt": { "type": "number", "description": "The time when the sandbox was requested, in milliseconds since the epoch." }, "startedAt": { "type": "number", "description": "The time when the sandbox was started, in milliseconds since the epoch." }, "cwd": { "type": "string", "description": "The working directory of the sandbox." }, "requestedStopAt": { "type": "number", "description": "The time when the sandbox was requested to stop, in milliseconds since the epoch." }, "stoppedAt": { "type": "number", "description": "The time when the sandbox was stopped, in milliseconds since the epoch." }, "abortedAt": { "type": "number", "description": "The time when the sandbox was aborted, in milliseconds since the epoch." }, "duration": { "type": "number", "description": "The duration of the sandbox in milliseconds." }, "sourceSnapshotId": { "type": "string", "description": "The unique identifier of the snapshot associated with this sandbox, if any." }, "snapshottedAt": { "type": "number", "description": "The time when a snapshot was requested, in milliseconds since the epoch." }, "createdAt": { "type": "number", "description": "The time when the sandbox was created, in milliseconds since the epoch." }, "updatedAt": { "type": "number", "description": "The last time the sandbox was updated, in milliseconds since the epoch." }, "networkPolicy": { "type": "object", "description": "The network policy applied to this sandbox, if any.", "required": [ "mode" ], "properties": { "mode": { "type": "string", "description": "The network policy mode. - 'allow-all': All traffic is allowed. - 'deny-all': All traffic is blocked. - 'custom': Traffic is controlled by explicit allow/deny rules.", "enum": [ "allow-all", "deny-all", "custom" ] }, "allowedDomains": { "type": "array", "description": "List of domain names the sandbox is allowed to connect to. Supports wildcard patterns (e.g., \"*.vercel.com\" matches all subdomains).", "items": { "type": "string" } }, "allowedCIDRs": { "type": "array", "description": "List of IP address ranges (in CIDR notation) the sandbox is allowed to connect to.", "items": { "type": "string" } }, "deniedCIDRs": { "type": "array", "description": "List of IP address ranges (in CIDR notation) the sandbox is blocked from connecting to. These rules take precedence over all allowed rules.", "items": { "type": "string" } }, "injectionRules": { "type": "array", "description": "HTTP header injection rules for outgoing requests matching specific domains.", "items": { "type": "object", "description": "HTTP header injection rules for outgoing requests matching specific domains.", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "The domain (or pattern) that this injection rule applies to. Supports wildcards like *.vercel.com." }, "headerNames": { "type": "array", "description": "The names of HTTP headers that have value that will be injected for requests to this domain.", "items": { "type": "string" } } } } } } }, "activeCpuDurationMs": { "type": "number", "description": "The amount of CPU time the sandbox consumed, if available, in milliseconds. This value is only available once the sandbox is stopped, and only if it stopped successfully." }, "networkTransfer": { "type": "object", "description": "The quantity of data transfered to and from the sandbox, in bytes. This value is only available once the sandbox is stopped, and only if it stopped successfully.", "required": [ "egress", "ingress" ], "properties": { "ingress": { "type": "number" }, "egress": { "type": "number" } } } } } }, "pagination": { "type": "object", "required": [ "count", "next" ], "properties": { "count": { "type": "number" }, "next": { "type": "string", "nullable": true } } } } } ] } ``` ### 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 ### 500: No description --- ## Related - [sandboxes-v2-beta endpoints](/docs/rest-api#sandboxes-v2-beta) - [REST API overview](/docs/rest-api) - [OpenAPI spec](https://openapi.vercel.sh/) (machine-readable, all endpoints) --- [View full sitemap](/docs/sitemap)