Get Sandbox

Get detailed information about a sandbox, including its current status, resources, and configuration.

Endpoint

GET /v1/sandboxes/:id

Request

Headers

Authorization: Bearer $HOPX_API_KEY

Path Parameters

Parameter	Type	Description
`id`	string	Sandbox ID

Example Request

curl https://api.hopx.dev/v1/sandboxes/sandbox_abc123xyz \
  -H "Authorization: Bearer $HOPX_API_KEY"

Response

Success (200 OK)

{
  "id": "sandbox_abc123xyz",
  "object": "sandbox",
  "status": "running",
  "public_host": "https://sandbox_abc123xyz.hopx.dev",
  "direct_url": "https://sandbox_abc123xyz.hopx.dev",
  "template_id": "73",
  "template_name": "code-interpreter",
  "organization_id": 123,
  "node_id": "node_xyz789",
  "region": "us-east",
  "resources": {
    "vcpu": 2,
    "memory_mb": 4096,
    "disk_mb": 10240
  },
  "internet_access": true,
  "timeout_seconds": 3600,
  "expires_at": "2025-01-29T00:00:00Z",
  "created_at": "2025-01-28T00:00:00Z"
}

Response Fields

Field	Type	Description
`id`	string	Sandbox ID
`status`	string	Current status (`running`, `stopped`, `paused`, `creating`)
`public_host`	string	VM Agent API base URL
`template_id`	string	Template ID used to create sandbox
`resources`	object	Allocated resources (vcpu, memory_mb, disk_mb)
`timeout_seconds`	integer	Auto-kill timeout in seconds
`expires_at`	string	ISO 8601 timestamp when sandbox expires

Status Codes

Code	Description
`200`	Success
`401`	Authentication required
`404`	Sandbox not found

Errors

Sandbox Not Found (404)

{
  "error": "Sandbox not found",
  "code": "RESOURCE_NOT_FOUND",
  "request_id": "req_abc123"
}

Cause: The sandbox ID doesn’t exist or belongs to another organization. Fix: Verify the sandbox ID is correct. List your sandboxes using GET /v1/sandboxes to find valid IDs.

Use Cases

Check Sandbox Status

Monitor sandbox status before executing code:

curl https://api.hopx.dev/v1/sandboxes/sandbox_abc123xyz \
  -H "Authorization: Bearer $HOPX_API_KEY" | jq '.status'

Verify Resources

Confirm allocated resources match expectations:

curl https://api.hopx.dev/v1/sandboxes/sandbox_abc123xyz \
  -H "Authorization: Bearer $HOPX_API_KEY" | jq '.resources'

SDK: Sandbox.connect() - Python SDK method
SDK: sandbox.get_info() - Python SDK method
CLI Sandbox Commands - Manage sandboxes from CLI

Next Steps

List Sandboxes - Query all your sandboxes
Update Sandbox - Modify sandbox configuration
Delete Sandbox - Clean up resources

Getting Started

Concepts

Control Plane API

VM Agent API

Endpoint

Request

Headers

Path Parameters

Example Request

Response

Success (200 OK)

Response Fields

Status Codes

Errors

Sandbox Not Found (404)

Use Cases

Check Sandbox Status

Verify Resources

Next Steps

​Endpoint

​Request

​Headers

​Path Parameters

​Example Request

​Response

​Success (200 OK)

​Response Fields

​Status Codes

​Errors

​Sandbox Not Found (404)

​Use Cases

​Check Sandbox Status

​Verify Resources

​Related

​Next Steps

Endpoint

Request

Headers

Path Parameters

Example Request

Response

Success (200 OK)

Response Fields

Status Codes

Errors

Sandbox Not Found (404)

Use Cases

Check Sandbox Status

Verify Resources

Related

Next Steps