Get sandbox by external ID

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

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

Get sandbox by external ID

cURL

curl --request GET \
  --url https://api.blaxel.ai/v0/sandboxes/by-external-id/{externalId} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.blaxel.ai/v0/sandboxes/by-external-id/{externalId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.blaxel.ai/v0/sandboxes/by-external-id/{externalId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.blaxel.ai/v0/sandboxes/by-external-id/{externalId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.blaxel.ai/v0/sandboxes/by-external-id/{externalId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.blaxel.ai/v0/sandboxes/by-external-id/{externalId}")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.blaxel.ai/v0/sandboxes/by-external-id/{externalId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

200

{
  "metadata": {
    "name": "my-resource",
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "createdBy": "<string>",
    "updatedBy": "<string>",
    "displayName": "My Resource",
    "externalId": "my-session-123",
    "labels": {},
    "plan": "<string>",
    "url": "<string>",
    "workspace": "<string>"
  },
  "spec": {
    "enabled": true,
    "lifecycle": {
      "expirationPolicies": [
        {
          "action": "delete",
          "type": "ttl-idle",
          "value": "24h"
        }
      ],
      "terminatedRetention": "24h"
    },
    "network": {
      "allowedDomains": "[\"api.stripe.com\", \"api.openai.com\", \"*.s3.amazonaws.com\"]",
      "egress": {
        "gateway": "egress-ip-gw-1",
        "mode": "dedicated",
        "policies": [
          {
            "destinations": "[\"api.stripe.com\"]",
            "mode": "dedicated",
            "name": "payment-apis"
          }
        ]
      },
      "firewall": {
        "rulesets": "[\"proxy\", \"dedicated-ip\"]"
      },
      "forbiddenDomains": "[\"*.malware.com\", \"evil.example.org\"]",
      "proxy": {
        "allowedDomains": "[\"api.stripe.com\", \"api.openai.com\", \"*.s3.amazonaws.com\"]",
        "bypass": "[\"*.s3.amazonaws.com\"]",
        "forbiddenDomains": "[\"*.malware.com\", \"evil.example.org\"]",
        "routing": [
          {
            "body": "{\"api_key\": \"{{SECRET:stripe-key}}\"}",
            "destinations": "[\"api.stripe.com\"]",
            "headers": "{\"Authorization\": \"Bearer {{SECRET:stripe-key}}\"}",
            "secrets": "{\"stripe-key\": \"sk-live-abc123...\"}"
          }
        ]
      },
      "subnet": "default"
    },
    "region": "us-pdx-1",
    "runtime": {
      "envs": [
        {
          "name": "MY_ENV_VAR",
          "secret": true,
          "value": "my-value"
        }
      ],
      "expires": "2025-12-31T23:59:59Z",
      "extraArgs": {},
      "image": "blaxel/base-image:latest",
      "memory": 4096,
      "ports": [
        {
          "target": 8080,
          "name": "http",
          "protocol": "HTTP"
        }
      ],
      "terminationGracePeriodSeconds": 30,
      "ttl": "24h"
    },
    "volumes": [
      {
        "mountPath": "/mnt/data",
        "name": "my-volume",
        "readOnly": false
      }
    ],
    "vpc": "default"
  },
  "events": [
    {
      "canaryRevision": "<string>",
      "message": "Deployment successful",
      "revision": "rev-abc123",
      "status": "DEPLOYED",
      "time": "2025-01-15T10:30:00Z",
      "type": "deployment"
    }
  ],
  "expiresIn": 123,
  "lastUsedAt": "<string>"
}

{
  "error": "Resource already exists",
  "code": 409,
  "message": "Invalid request body"
}

{
  "error": "Resource already exists",
  "code": 409,
  "message": "Invalid request body"
}

{
  "error": "Resource already exists",
  "code": 409,
  "message": "Invalid request body"
}

{
  "error": "Resource already exists",
  "code": 409,
  "message": "Invalid request body"
}

Authorizations

OAuth2ApiKeyAuth

Authorization · string · header · required

OAuth2 authentication with JWT tokens

Path Parameters

externalId · string · required

Caller-owned external identifier for the sandbox

Response

200

application/json

successful operation

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.

metadata · object · required

Common metadata fields shared by all Blaxel resources including name, labels, timestamps, and ownership information

Show child attributes

spec · object · required

Configuration for a sandbox including its image, memory, ports, region, and lifecycle policies

Show child attributes

events · object[] · read-only

Events happening on a resource deployed on Blaxel

Show child attributes

expiresIn · integer · read-only

Time in seconds until the sandbox is automatically deleted based on TTL and lifecycle policies. Only present for sandboxes with lifecycle configured.

lastUsedAt · string · read-only

Last time the sandbox was used (read-only, managed by the system)

state · enum<string> · read-only

Current state of the sandbox (read-only, managed by the system)

Available options: RUNNING, STANDBY

status · enum<string> · read-only

Deployment status of a resource deployed on Blaxel

Available options: DELETING, TERMINATED, FAILED, DEACTIVATED, DEACTIVATING, UPLOADING, BUILDING, DEPLOYING, DEPLOYED, BUILT