--- title: delete-a-sandbox product: vercel url: /docs/rest-api/sandboxes/delete-a-sandbox canonical_url: "https://vercel.com/docs/rest-api/sandboxes/delete-a-sandbox" last_updated: 2026-10-16 type: reference prerequisites: [] related: - /docs/rest-api summary: Learn about delete-a-sandbox on Vercel. install_vercel_plugin: npx plugins add vercel/vercel-plugin --- # Delete a sandbox ```http DELETE /v2/sandboxes/{name} ``` Deletes a sandbox by name. If sandboxes are currently running, they will be stopped first. This operation deletes all sandbox entities with the given name and the named sandbox metadata. When the config item is already missing, the returned sandbox uses stored metadata and defaults; config fields may be stale. ## Authentication **bearerToken**: HTTP bearer ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `name` | string. maxLength: 128; pattern: `^[a-zA-Z0-9_-]+$` | Yes | The sandbox name to delete. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `projectId` | string. maxLength: 128 | No | The project ID that owns the named sandbox. When provided, takes precedence over OIDC project context. | | `deleteOrphanSnapshots` | boolean. default: false | No | When true, snapshots of the deleted sandbox that are not referenced by any other sandbox are also deleted asynchronously. Defaults to false. | | `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/name?projectId=string&deleteOrphanSnapshots=true&teamId=string&slug=string', { method: 'DELETE', 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/name?projectId=string&deleteOrphanSnapshots=true&teamId=string&slug=string', { method: 'DELETE', 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 DELETE 'https://api.vercel.com/v2/sandboxes/name?projectId=string&deleteOrphanSnapshots=true&teamId=string&slug=string' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'Content-Type: application/json' ``` ## Example response ```json { "sandbox": { "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": [ "sandbox" ], "properties": { "sandbox": { "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.", "items": { "type": "string", "description": "The regions the sandbox fails over to. Empty when it does not fail over.", "enum": [ "arn1", "bom1", "cdg1", "cle1", "cpt1", "dub1", "fra1", "gru1", "hkg1", "hnd1", "iad1", "icn1", "kix1", "lhr1", "pdx1", "sfo1", "sin1", "syd1", "yul1" ] } }, "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" ], "properties": { "count": { "type": "number", "description": "Number of most recent snapshots to keep." }, "deleteEvicted": { "type": "boolean", "description": "Whether to immediately delete evicted snapshots.", "enum": [ false, true ] }, "expiration": { "type": "number", "description": "Expiration time in milliseconds for kept snapshots." } } }, "memory": { "type": "number", "description": "Memory allocated in MB." }, "mounts": { "type": "object", "description": "Key-value pairs of mount path and drive.", "additionalProperties": { "type": "object", "description": "Key-value pairs of mount path and drive.", "required": [ "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" ], "properties": { "allowedCIDRs": { "type": "array" }, "allowedDomains": { "type": "array" }, "deniedCIDRs": { "type": "array" }, "mode": { "type": "string", "enum": [ "allow-all", "custom", "default-allow", "default-deny", "deny-all" ] }, "s3Key": { "type": "string" } } }, "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.", "additionalProperties": { "type": "string" } }, "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)