---
title: stop-a-session
product: vercel
url: /docs/rest-api/sandboxes-v2-beta/stop-a-session
canonical_url: "https://vercel.com/docs/rest-api/sandboxes-v2-beta/stop-a-session"
last_updated: 2026-05-07
type: reference
prerequisites:
  []
related:
  - /docs/rest-api
summary: Learn about stop-a-session on Vercel.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

# Stop a session

```http
POST /v2/sandboxes/sessions/{sessionId}/stop
```

Stops a running session and releases its allocated resources. All running processes within the session will be terminated. This action cannot be undone. A stopped session cannot be restarted.

## Authentication

**bearerToken**: HTTP bearer

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `sessionId` | string | Yes | The unique identifier of the session to stop. |


## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `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 session was stopped successfully.

Content-Type: `application/json`

```json
{
  "oneOf": [
    {
      "type": "object",
      "required": [
        "session"
      ],
      "properties": {
        "session": {
          "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"
              ]
            },
            "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"
              ]
            }
          }
        }
      }
    },
    {
      "type": "object",
      "required": [
        "sandbox",
        "session",
        "snapshot"
      ],
      "properties": {
        "snapshot": {
          "type": "object",
          "description": "This object contains information related to a Snapshot of a Vercel Sandbox session (v2 API).",
          "required": [
            "createdAt",
            "id",
            "lastUsedAt",
            "region",
            "sizeBytes",
            "sourceSessionId",
            "status",
            "updatedAt"
          ],
          "properties": {
            "id": {
              "type": "string",
              "description": "The unique identifier of the snapshot."
            },
            "sourceSessionId": {
              "type": "string",
              "description": "The unique identifier of the session from which the snapshot was created."
            },
            "region": {
              "type": "string",
              "description": "The region where the snapshot is stored."
            },
            "status": {
              "type": "string",
              "description": "The status of the snapshot.",
              "enum": [
                "failed",
                "created",
                "deleted"
              ]
            },
            "sizeBytes": {
              "type": "number",
              "description": "The size of the snapshot in bytes."
            },
            "expiresAt": {
              "type": "number",
              "description": "The time when the snapshot will expire, in milliseconds since the epoch. If not set, the snapshot does not have any expiration."
            },
            "createdAt": {
              "type": "number",
              "description": "The time when the snapshot was created, in milliseconds since the epoch."
            },
            "updatedAt": {
              "type": "number",
              "description": "The last time the snapshot was updated, in milliseconds since the epoch."
            },
            "lastUsedAt": {
              "type": "number",
              "description": "The last time the snapshot was used (e.g. to resume or create a sandbox), in milliseconds since the epoch. Falls back to `createdAt` for older snapshots that predate this field."
            },
            "creationMethod": {
              "type": "string",
              "description": "The method used to create the snapshot.",
              "enum": [
                "manual",
                "automatic"
              ]
            },
            "parentId": {
              "type": "string",
              "description": "The unique identifier of the parent snapshot, if this snapshot was created from another snapshot."
            }
          }
        },
        "sandbox": {
          "type": "object",
          "description": "This object contains information related to a Vercel NamedSandbox.",
          "required": [
            "createdAt",
            "currentSessionId",
            "name",
            "persistent",
            "status",
            "statusUpdatedAt",
            "updatedAt"
          ],
          "properties": {
            "name": {
              "type": "string",
              "description": "The unique identifier of the sandbox."
            },
            "currentSnapshotId": {
              "type": "string",
              "description": "Current snapshot ID that the named sandbox is pointing to."
            },
            "currentSessionId": {
              "type": "string",
              "description": "Current session ID the sandbox is pointing to."
            },
            "status": {
              "type": "string",
              "description": "The status of the current sandbox.",
              "enum": [
                "stopping",
                "running",
                "stopped"
              ]
            },
            "statusUpdatedAt": {
              "type": "number",
              "description": "The time when the sandbox status was last updated, in milliseconds since the epoch."
            },
            "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 runs in."
            },
            "vcpus": {
              "type": "number",
              "description": "Number of virtual CPUs allocated."
            },
            "memory": {
              "type": "number",
              "description": "Memory allocated in MB."
            },
            "runtime": {
              "type": "string",
              "description": "Runtime identifier."
            },
            "timeout": {
              "type": "number",
              "description": "Timeout in milliseconds."
            },
            "snapshotExpiration": {
              "type": "number",
              "description": "Default snapshot expiration time in milliseconds. 0 means no expiration."
            },
            "keepLastSnapshots": {
              "type": "object",
              "description": "Keep-last snapshot configuration.",
              "required": [
                "count",
                "deleteEvicted"
              ]
            },
            "networkPolicy": {
              "type": "object",
              "description": "Network policy configuration.",
              "required": [
                "mode"
              ]
            },
            "totalEgressBytes": {
              "type": "number",
              "description": "Cumulative egress bytes across all sandbox runs."
            },
            "totalIngressBytes": {
              "type": "number",
              "description": "Cumulative ingress bytes across all sandbox runs."
            },
            "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."
            },
            "cwd": {
              "type": "string",
              "description": "The working directory of the sandbox."
            },
            "tags": {
              "type": "object",
              "description": "Key-value tags attached to the named sandbox."
            },
            "createdAt": {
              "type": "number",
              "description": "The time when the named sandbox was created, in milliseconds since the epoch."
            },
            "updatedAt": {
              "type": "number",
              "description": "The time when the named sandbox was last updated, in milliseconds since the epoch."
            }
          }
        },
        "session": {
          "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"
              ]
            },
            "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"
              ]
            }
          }
        }
      }
    }
  ]
}
```

### 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.

### 410: No description

### 422: 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)