Sign in

v13

OpenAPI 3.0.32026-07-31359869.4 MB
sandboxes

Get a named sandbox

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.

get/v2/sandboxes/{name}

Path parameters

namestring required

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

Example:my-sandbox

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

Query parameters

projectIdstring

The project ID or name (required when not using OIDC token).

Example:prj_abc123

The project ID or name (required when not using OIDC token).

resumeboolean

Whether to automatically resume a stopped named sandbox by creating a new instance from its snapshot. Defaults to false.

Whether to automatically resume a stopped named sandbox by creating a new instance from its snapshot. Defaults to false.

teamIdstring
Example:team_1a2b3c4d5e6f7g8h9i0j1k2l

The Team identifier to perform the request on behalf of.

slugstring
Example:my-team-url-slug

The Team slug to perform the request on behalf of.

Response

resumedfalse | true required

Example response

{
  "sandbox": {
    "name": "my-sandbox",
    "status": "running",
    "statusUpdatedAt": 1750344501629,
    "persistent": true,
    "region": "iad1",
    "vcpus": 2,
    "memory": 1024,
    "runtime": "node22",
    "image": "my-repo@sha256:2c4e8f9a1b3d5e7f091a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708",
    "timeout": 300000,
    "snapshotExpiration": 604800000,
    "keepLastSnapshots": {
      "count": 5,
      "expiration": 604800000,
      "deleteEvicted": true
    },
    "totalEgressBytes": 4096,
    "totalIngressBytes": 2048,
    "totalActiveCpuDurationMs": 5000,
    "totalDurationMs": 60000,
    "cwd": "/vercel/sandbox",
    "tags": {
      "team": "hive",
      "user": "bob"
    },
    "createdAt": 1750344501629,
    "updatedAt": 1750344501629,
    "expiresAt": 1750344801629
  },
  "session": {
    "sourceSandboxName": "my-sandbox",
    "projectId": "prj_123a6c5209bc3778245d011443644c8d27dc2c50",
    "id": "sbx_123a6c5209bc3778245d011443644c8d27dc2c50",
    "memory": 2048,
    "vcpus": 2,
    "region": "iad1",
    "runtime": "node22",
    "timeout": 3600000,
    "status": "running",
    "requestedAt": 1750344501629,
    "startedAt": 1750344501629,
    "cwd": "/vercel/sandbox",
    "requestedStopAt": 1750344501629,
    "stoppedAt": 1750344501629,
    "abortedAt": 1750344501629,
    "duration": 3600000,
    "sourceSnapshotId": "snap_123a6c5209bc3778245d011443644c8d27dc2c50",
    "snapshottedAt": 1750344501629,
    "createdAt": 1750344501629,
    "updatedAt": 1750344501629,
    "networkPolicy": {
      "mode": "custom",
      "allowedDomains": [
        "api.vercel.com",
        "*.example.com"
      ],
      "allowedCIDRs": [
        "10.0.0.0/8"
      ],
      "deniedCIDRs": [
        "10.0.0.0/8"
      ],
      "injectionRules": [
        {
          "domain": "api.vercel.com",
          "headerNames": [
            "Authorization",
            "X-API-Key"
          ]
        }
      ]
    },
    "activeCpuDurationMs": 42,
    "networkTransfer": {
      "in": 12543852,
      "out": 15368
    }
  }
}