Skip to content
Docs

Get a named sandbox

GEThttps://api.vercel.com/v2/sandboxes/{name}
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.
Request
import { Vercel } from "@vercel/sdk";


const vercel = new Vercel({
  bearerToken: "<YOUR_BEARER_TOKEN_HERE>",
});


async function run() {
  const result = await vercel.sandboxes.getNamedSandbox({
    name: "my-sandbox",
    projectId: "prj_abc123",
    teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l",
    slug: "my-team-url-slug",
  });


  console.log(result);
}


run();
Response
{
  "resumed": "false",
  "routes": [
    {
      "port": "123",
      "subdomain": "string",
      "system": "true",
      "url": "https://example.com"
    }
  ],
  "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"
  },
  "session": {
    "abortedAt": "1750344501629",
    "activeCpuDurationMs": "42",
    "architecture": "amd64",
    "createdAt": "1750344501629",
    "cwd": "/vercel/sandbox",
    "duration": "3600000",
    "id": "sbx_123a6c5209bc3778245d011443644c8d27dc2c50",
    "memory": "2048",
    "networkPolicy": {
      "allowedCIDRs": [],
      "allowedDomains": [],
      "deniedCIDRs": [],
      "injectionRules": [
        {
          "domain": "api.vercel.com",
          "headerNames": []
        }
      ],
      "mode": "custom"
    },
    "networkTransfer": {
      "egress": "123",
      "ingress": "123"
    },
    "projectId": "prj_123a6c5209bc3778245d011443644c8d27dc2c50",
    "region": "iad1",
    "requestedAt": "1750344501629",
    "requestedStopAt": "1750344501629",
    "runtime": "node22",
    "snapshottedAt": "1750344501629",
    "sourceSandboxName": "my-sandbox",
    "sourceSnapshotId": "snap_123a6c5209bc3778245d011443644c8d27dc2c50",
    "startedAt": "1750344501629",
    "status": "running",
    "stoppedAt": "1750344501629",
    "timeout": "3600000",
    "updatedAt": "1750344501629",
    "v0": "false",
    "vcpus": "2"
  }
}

Authentication

AuthorizationbearerToken

Default authentication mechanism

Path parameters

namestringRequired
Name for the sandbox. Must be unique per project and URL-safe (alphanumeric, hyphens, underscores).

Query parameters

projectIdstringOptional
The project ID or name (required when not using OIDC token).
resumebooleanOptional
Whether to automatically resume a stopped named sandbox by creating a new instance from its snapshot. Defaults to false.
teamIdstringOptional
The Team identifier to perform the request on behalf of.
slugstringOptional
The Team slug to perform the request on behalf of.

Response

200Success
resumedbooleanRequired
routesarrayRequired
sandboxobjectRequired
This object contains information related to a Vercel NamedSandbox.
sessionobjectRequired
This object contains information related to a Vercel Sandbox Session. v2 endpoints return "session" instead of "sandbox" as the response wrapper key.

Errors

400One of the provided values in the request query is invalid.
401The request is not authorized.
402The account is missing a payment so payment method must be updated
403You do not have permission to access this resource.
404Error
409Error
410Error
422Error
429The concurrency limit has been exceeded.
500Error
502Error