---
title: "Get sandbox by external ID"
method: GET
path: "/sandboxes/by-external-id/{externalId}"
tags: ["compute"]
---

# Get sandbox by external ID

`GET /sandboxes/by-external-id/{externalId}`

## Request

- Base URL: `https://api.blaxel.ai/v0`
- URL: `https://api.blaxel.ai/v0/sandboxes/by-external-id/{externalId}`
- Auth: one of:
  - OAuth 2
    - Authorization code: `/oauth/authorize`
    - Client credentials
    - Token URL: `/oauth/token` scopes: `sandboxes:get`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/blaxel/apis/blaxel-control-plane/docs/sandboxes/by-external-id/:externalId/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns the most recent non-terminated sandbox matching the given external ID. If no active sandbox is found, returns 404.

## Response `200`

successful operation

- Sandbox: Lightweight virtual machine for secure AI code execution. Sandboxes resume from standby in under 25ms and automatically scale to zero after inactivity, preserving memory state including running processes and filesystem.
  - `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

## Other responses

- `401`: Unauthorized - Invalid or missing authentication credentials
- `403`: Forbidden - Insufficient permissions to view sandboxes
- `404`: Not found - No active sandbox with this external ID
- `500`: Internal server error

---

[API](https://skmtc.dev/blaxel/apis/blaxel-control-plane.md) - [All operations](https://skmtc.dev/blaxel/apis/blaxel-control-plane/llms.txt) - [OpenAPI document](https://skmtc.dev/blaxel/apis/blaxel-control-plane/revisions/dfa264bc72ee?raw)