--- title: "Get a named sandbox" method: GET path: "/v2/sandboxes/{name}" tags: ["sandboxes"] --- # Get a named sandbox `GET /v2/sandboxes/{name}` ## Request - Base URL: `https://api.vercel.com` - URL: `https://api.vercel.com/v2/sandboxes/{name}` - Auth: HTTP bearer Retrieves a named sandbox by name, including its current sandbox and routes. If the sandbox is stopped and resume is true, a new sandbox will be created from the most recent snapshot. Returns 404 if the named sandbox or its configuration no longer exists. ## Path parameters - `name` string, required: Name for the sandbox. Must be unique per project and URL-safe (alphanumeric, hyphens, underscores). ## Query parameters - `projectId` string: The project ID or name (required when not using OIDC token). - `resume` boolean: Whether to automatically resume a stopped named sandbox by creating a new instance from its snapshot. Defaults to false. - `teamId` string - `slug` string ## Response `200` - object - `resumed` false | true, required - `routes` SandboxPublicRoute[], required - `port` number, required: The user port number that the route is mapped to. - `subdomain` string, required: The subdomain assigned to this route. - `system` true: Whether the route is reserved by the system (e.g. for internal use). - `url` string, required: A public URL to access the corresponding port in the Sandbox. - `sandbox` NamedSandbox, required: This object contains information related to a Vercel NamedSandbox. - `architecture` 'amd64' | 'arm64': CPU architecture of the sandbox. This value does not change. - `createdAt` number, required: The time when the named sandbox was created, in milliseconds since the epoch. - `currentSessionId` string, required: Current session ID the sandbox is pointing to. - `currentSnapshotId` string: Current snapshot ID that the named sandbox is pointing to. - `cwd` string: The working directory of the sandbox. - `expiresAt` number: The time at which the currently running sandbox will time out, in milliseconds since the epoch. Only present while a session is running. - `failoverRegions` string[]: The regions the sandbox fails over to. Empty when it does not fail over. - `image` string: Owner-qualified, digest-pinned reference of the container image the sandbox was created from ("{team}/{project}/{repository}@{manifestDigest}"). - `keepLastSnapshots` object: Keep-last snapshot configuration. - `count` number, required: Number of most recent snapshots to keep. - `deleteEvicted` false | true, required: Whether to immediately delete evicted snapshots. - `expiration` number: Expiration time in milliseconds for kept snapshots. - `memory` number: Memory allocated in MB. - `mounts` object: Key-value pairs of mount path and drive. - `name` string, required: The unique identifier of the sandbox. - `networkId` string: The Connect network id for the target Secure Compute private network. - `networkPolicy` object: Network policy configuration. - `allowedCIDRs` string[] - `allowedDomains` string[] - `deniedCIDRs` string[] - `mode` 'allow-all' | 'custom' | 'default-allow' | 'default-deny' | 'deny-all', required - `s3Key` string - `persistent` false | true, required: Whether the sandbox persists its state across restarts via automatic snapshots. - `region` string: 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` string: Runtime identifier. - `snapshotExpiration` number: Default snapshot expiration time in milliseconds. 0 means no expiration. - `status` 'running' | 'stopped' | 'stopping', required: The status of the current sandbox. - `statusUpdatedAt` number, required: The time when the sandbox status was last updated, in milliseconds since the epoch. - `tags` object: Key-value tags attached to the named sandbox. - `timeout` number: Timeout in milliseconds. - `totalActiveCpuDurationMs` number: Cumulative active CPU duration in milliseconds across all sandbox runs. - `totalDurationMs` number: Cumulative wall-clock duration in milliseconds across all sandbox runs. - `totalEgressBytes` number: Cumulative egress bytes across all sandbox runs. - `totalIngressBytes` number: Cumulative ingress bytes across all sandbox runs. - `updatedAt` number, required: The time when the named sandbox was last updated, in milliseconds since the epoch. - `vcpus` number: Number of virtual CPUs allocated. - `workloadType` 'sandbox' | 'v0': The workload type of this sandbox. - `session` Session, required: This object contains information related to a Vercel Sandbox Session. v2 endpoints return "session" instead of "sandbox" as the response wrapper key. - `abortedAt` number: The time when the sandbox was aborted, in milliseconds since the epoch. - `activeCpuDurationMs` number: 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. - `architecture` 'amd64' | 'arm64': CPU architecture of the sandbox. - `createdAt` number, required: The time when the sandbox was created, in milliseconds since the epoch. - `cwd` string, required: The working directory of the sandbox. - `duration` number: The duration of the sandbox in milliseconds. - `id` string, required: The unique identifier of the sandbox. - `memory` number, required: Memory allocated to this sandbox in MB. - `networkPolicy` SandboxNetworkPolicy: The network policy applied to this sandbox, if any. - `allowedCIDRs` string[]: List of IP address ranges (in CIDR notation) the sandbox is allowed to connect to. - `allowedDomains` string[]: List of domain names the sandbox is allowed to connect to. Supports wildcard patterns (e.g., "*.vercel.com" matches all subdomains). - `deniedCIDRs` string[]: List of IP address ranges (in CIDR notation) the sandbox is blocked from connecting to. These rules take precedence over all allowed rules. - `injectionRules` SandboxInjectionRule[]: HTTP header injection rules for outgoing requests matching specific domains. - `domain` string, required: The domain (or pattern) that this injection rule applies to. Supports wildcards like *.vercel.com. - `headerNames` string[]: The names of HTTP headers that have value that will be injected for requests to this domain. - `mode` 'allow-all' | 'custom' | 'deny-all', required: 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. - `networkTransfer` object: 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. - `egress` number, required - `ingress` number, required - `projectId` string, required: The unique identifier of the project associated with this session. - `region` string, required: The region where the sandbox is hosted. - `requestedAt` number, required: The time when the sandbox was requested, in milliseconds since the epoch. - `requestedStopAt` number: The time when the sandbox was requested to stop, in milliseconds since the epoch. - `runtime` string, required: The runtime of the sandbox. - `snapshottedAt` number: The time when a snapshot was requested, in milliseconds since the epoch. - `sourceSandboxName` string, required: The name of the source sandbox. - `sourceSnapshotId` string: The unique identifier of the snapshot associated with this sandbox, if any. - `startedAt` number: The time when the sandbox was started, in milliseconds since the epoch. - `status` 'aborted' | 'failed' | 'pending' | 'running' | 'snapshotting' | 'stopped' | 'stopping', required: The status of the sandbox. - `stoppedAt` number: The time when the sandbox was stopped, in milliseconds since the epoch. - `timeout` number, required: The maximum amount of time the sandbox will run for in milliseconds. - `updatedAt` number, required: The last time the sandbox was updated, in milliseconds since the epoch. - `vcpus` number, required: Number of vCPUs allocated to this sandbox. - `workloadType` 'sandbox' | 'v0': The workload type of this sandbox. ## Other responses - `400`: One of the provided values in the request query is invalid. - `401`: The request is not authorized. - `402`: The account is missing a payment so payment method must be updated - `403`: You do not have permission to access this resource. - `404` - `409` - `410` - `422` - `429`: The concurrency limit has been exceeded. - `500` - `502` - `503` ## Changes - **2026-10-26** `01d3fe4ea5c3`: 2 warning, 2 info - removed the optional property `sandbox/v0` from the response with the `200` status - removed the optional property `session/v0` from the response with the `200` status - added the optional property `sandbox/workloadType` to the response with the `200` status - added the optional property `session/workloadType` to the response with the `200` status - **2026-10-10** `32399b3ed273`: 1 info - added the non-success response with the status `503` - **2026-10-09** `336a06c75674`: 1 info - added the optional property `sandbox/mounts/additionalProperties/snapshot` to the response with the `200` status - **2026-10-01** `9958fd10bb05`: 2 info - added the optional property `sandbox/v0` to the response with the `200` status - added the optional property `session/v0` to the response with the `200` status - **2026-09-22** `4f8704cf40ba`: 1 info - added the non-success response with the status `422` [Operation history](https://skmtc.dev/vercel/apis/vercel-api/changes/v2/sandboxes/:name/get.md) --- [API](https://skmtc.dev/vercel/apis/vercel-api.md) - [All operations](https://skmtc.dev/vercel/apis/vercel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vercel/apis/vercel-api/revisions/60686c0e1f6a?raw)