--- title: "List sandboxes" method: GET path: "/sandboxes" tags: ["compute"] --- # List sandboxes `GET /sandboxes` Returns sandboxes in the workspace. Each sandbox includes its configuration, status, and endpoint URL. Terminated sandboxes are hidden by default; pass `showTerminated=true` to include them. Starting with API version 2026-04-28 the response is wrapped in `{data, meta}` and supports cursor pagination via the `cursor` and `limit` query parameters; older versions keep returning a bare array of all sandboxes. ## Query parameters - `showTerminated` boolean - `cursor` string - `limit` integer - `sort` 'createdAt:desc' | 'createdAt:asc' | 'name:asc' | 'name:desc' - `q` string - `anchor` 'end' - `externalId` string ## Response `200` successful operation - SandboxList — Cursor-paginated list of sandboxes. Returned starting with API version 2026-04-28; older API versions return a bare array. - `data` Sandbox[] — Page of sandboxes. Items use the lite shape (no inline event history) to keep the page payload small, matching the unpaginated response. - `events` CoreEvent[] — Events happening on a resource deployed on Blaxel - `canaryRevision` string — Canary revisionID link to the event - `message` string — Event message - `revision` string — RevisionID link to the event - `status` string — Event status - `time` string — Event time - `type` string — Event type - `expiresIn` integer — Time in seconds until the sandbox is automatically deleted based on TTL and lifecycle policies. Only present for sandboxes with lifecycle configured. - `lastUsedAt` string — Last time the sandbox was used (read-only, managed by the system) - `metadata` Metadata, required — Owner fields for Persistence - `createdAt` string — The date and time when the resource was created - `updatedAt` string — The date and time when the resource was updated - `createdBy` string — The user or service account who created the resource - `updatedBy` string — The user or service account who updated the resource - `displayName` string — Human-readable name for display in the UI. Can contain spaces and special characters, max 63 characters. - `externalId` string — Caller-owned identifier for external lookups. Max 64 chars, alphanumeric + dash. - `labels` MetadataLabels — Key-value pairs for organizing and filtering resources. Labels can be used to categorize resources by environment, project, team, or any custom taxonomy. - `name` string, required — Unique identifier for the resource within the workspace. Must be lowercase alphanumeric with hyphens, max 49 characters. Immutable after creation. - `plan` string — Billing plan tier applied to this resource (inherited from workspace account) - `url` string — Auto-generated endpoint URL for accessing this resource (for agents, functions, models, sandboxes) - `workspace` string — Name of the workspace this resource belongs to (read-only, set automatically) - `nodeGeneration` string — Infrastructure generation this sandbox is deployed on (mk3.0 or mk3.1). Read-only. - `spec` SandboxSpec, required — Configuration for a sandbox including its image, memory, ports, region, and lifecycle policies - `enabled` boolean — When false, the sandbox is disabled and will not accept connections - `lifecycle` SandboxLifecycle — Lifecycle configuration controlling automatic sandbox deletion based on idle time, max age, or specific dates - `expirationPolicies` ExpirationPolicy[] — List of expiration policies. Multiple policies can be combined; whichever condition is met first triggers the action. - `action` 'delete' — Action to take when the expiration condition is met - `type` 'ttl-idle' | 'ttl-max-age' | 'date' — Type of expiration policy: ttl-idle (delete after inactivity), ttl-max-age (delete after total lifetime), or date (delete at specific time) - `value` string — Duration value for TTL policies (e.g., '30m', '24h', '7d') or ISO 8601 date for date policies - `terminatedRetention` string — Duration to keep the sandbox record after termination for log access (e.g., '1h', '24h', '7d'). Defaults to 5m. Subject to maximum quota limits. - `network` SandboxNetwork — Network configuration for a sandbox including subnet, firewall rulesets, domain filtering, egress IP binding, and proxy settings - `allowedDomains` string[] — Deprecated: use proxy.allowedDomains instead. List of allowed external domains (allowlist). Kept for backward compatibility. - `egress` EgressConfig — Egress configuration for routing sandbox outbound traffic through a dedicated IP gateway - `gateway` string — Name of the egress gateway to route traffic through. The gateway must exist in the default VPC. - `mode` string — Egress mode. Use 'dedicated' for a dedicated egress IP. - `policies` EgressPolicy[] — Per-destination egress policies (not yet supported) - `destinations` string[] — Destination domains or IPs this policy applies to - `mode` string — Egress mode for these destinations (dedicated or shared) - `name` string — Name of this egress policy - `firewall` FirewallConfig — Firewall configuration specifying which network lockdown rulesets to apply. Valid rulesets are "default" (no-op), "proxy" (restrict egress to proxy), and "dedicated-ip" (restrict egress to dedicated IP gateway). - `rulesets` string[] — List of firewall rulesets to apply. Valid values: "default" (no-op), "proxy" (restrict egress to proxy), "dedicated-ip" (restrict egress to dedicated IP gateway). - `forbiddenDomains` string[] — Deprecated: use proxy.forbiddenDomains instead. List of forbidden external domains (denylist). Kept for backward compatibility. - `proxy` ProxyConfig — Proxy configuration for routing sandbox HTTP traffic through the platform proxy with MITM inspection and per-destination header/body injection - `allowedDomains` string[] — List of allowed external domains (allowlist). When set, only these domains are reachable. Supports wildcards (e.g. *.s3.amazonaws.com). - `bypass` string[] — Domains that bypass the proxy entirely via the NO_PROXY directive. Traffic to these destinations goes direct, not through the CONNECT tunnel. Supports wildcards. Note that localhost, private ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), 169.254.169.254, .local and .internal are always bypassed by default. - `forbiddenDomains` string[] — List of forbidden external domains (denylist). When set, all domains except these are reachable. Supports wildcards (e.g. *.malware.com). If both allowedDomains and forbiddenDomains are set, allowedDomains takes precedence. - `routing` ProxyTarget[] — Per-destination routing rules with header/body injection and secrets. Use destinations ["*"] for global rules that apply to all destinations. - `body` object — Body fields to inject into matching requests. Values may contain {{SECRET:name}} references resolved from this rule's secrets. - `destinations` string[] — Destination domains this rule applies to. Use ["*"] for a global rule that matches all destinations. - `headers` object — Headers to inject into matching requests. Values may contain {{SECRET:name}} references resolved from this rule's secrets. - `secrets` object — Named secret values for this routing rule, referenced in headers/body via {{SECRET:name}}. Stored encrypted at rest. Write-only: never returned in API responses. - `subnet` string — Subnet name for the sandbox. Takes priority over any subnet derived from egress config. Defaults to "default" when absent. - `region` string — Region where the sandbox should be created (e.g. us-pdx-1, eu-lon-1). If not specified, defaults to the region closest to the user. - `runtime` SandboxRuntime — Runtime configuration defining how the sandbox VM is provisioned and its resource limits - `envs` Env[] — Environment variables injected into the sandbox. Supports Kubernetes EnvVar format with valueFrom references. - `name` string — Name of the environment variable - `secret` boolean — Whether the value is a secret - `value` string — Value of the environment variable - `expires` string — Absolute expiration timestamp in ISO 8601 format when the sandbox will be deleted - `extraArgs` object — Extra arguments for kernel selection. Supported keys: 'iptables', 'nfs' (mk3.0), 'tun' (mk3.1). Values: 'enabled' or 'disabled'. Determines which kernel variant the workload runs on. Immutable after creation. - `image` string — Sandbox image to use. Can be a public Blaxel image (e.g., blaxel/base-image:latest) or a custom template image built with 'bl deploy'. - `memory` integer — Memory allocation in megabytes. Also determines CPU allocation (CPU cores = memory in MB / 2048, e.g., 4096MB = 2 CPUs). - `ports` Port[] — Set of ports for a resource - `name` string — The name of the port - `protocol` 'HTTP' | 'TCP' | 'UDP' | 'TLS' — The protocol of the port - `target` integer, required — The target port of the port - `terminationGracePeriodSeconds` integer — Duration in seconds the pod needs to terminate gracefully. Defaults to 0 for immediate termination. - `ttl` string — Max-age from creation: the sandbox is deleted this long after it is created, regardless of activity (not an idle timeout). Units s, m, h, d, w (e.g., '30m', '24h', '7d', '2w'). For idle-based cleanup, use a lifecycle expiration policy of type ttl-idle. - `volumes` VolumeAttachment[] - `mountPath` string — Absolute filesystem path where the volume will be mounted inside the sandbox - `name` string — Name of the volume resource to attach (must exist in the same workspace and region) - `readOnly` boolean — If true, the volume is mounted read-only and cannot be modified by the sandbox - `vpc` string — VPC name for the sandbox. Defaults to "default" when absent. - `state` 'RUNNING' | 'STANDBY' — Current state of the sandbox (read-only, managed by the system) - `status` 'DELETING' | 'TERMINATED' | 'FAILED' | 'DEACTIVATED' | 'DEACTIVATING' | 'UPLOADING' | 'BUILDING' | 'DEPLOYING' | 'DEPLOYED' | 'BUILT' — Deployment status of a resource deployed on Blaxel - `meta` PaginationMeta — Pagination metadata returned alongside a page of listing results. Always present on listing endpoints starting with API version 2026-04-28. - `hasMore` boolean — True when more pages are available beyond the current one. - `nextCursor` string — Opaque cursor to pass back as the `cursor` query param for the next page. Empty when there are no more pages. - `total` integer — Total number of items in the workspace, ignoring the current page's filters. Lets the UI render "page X of Y" without walking the cursor chain. Computed from the hash-only metadata.workspace GSI count, so search (`q`) does not narrow it. ## Other responses - `401` — Unauthorized - Invalid or missing authentication credentials - `403` — Forbidden - Insufficient permissions to list sandboxes - `500` — Internal server error --- [API](https://skmtc.net/blaxel/apis/blaxel-control-plane.md) · [All operations](https://skmtc.net/blaxel/apis/blaxel-control-plane/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/blaxel/blaxel-control-plane/versions/dfa264bc72ee/schema)