List Sandboxes

List all sandboxes in your organization. Filter by status, region, or use pagination to handle large result sets.

Endpoint

GET /v1/sandboxes

Request

Headers

Authorization: Bearer $HOPX_API_KEY

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Maximum number of results (default: 100, max: 1000)
`status`	string	No	Filter by status: `running`, `stopped`, `paused`, `creating`
`region`	string	No	Filter by region (e.g., `us-east`, `eu-west`)
`cursor`	string	No	Pagination cursor for next page

Example Request

List all running sandboxes:

curl "https://api.hopx.dev/v1/sandboxes?status=running&limit=10" \
  -H "Authorization: Bearer $HOPX_API_KEY"

Filter by region:

curl "https://api.hopx.dev/v1/sandboxes?region=us-east" \
  -H "Authorization: Bearer $HOPX_API_KEY"

Paginated request:

curl "https://api.hopx.dev/v1/sandboxes?limit=20&cursor=abc123" \
  -H "Authorization: Bearer $HOPX_API_KEY"

Response

Success (200 OK)

{
  "object": "list",
  "data": [
    {
      "id": "sandbox_abc123",
      "object": "sandbox",
      "status": "running",
      "public_host": "https://sandbox_abc123.hopx.dev",
      "template_name": "code-interpreter",
      "region": "us-east",
      "created_at": "2025-01-28T00:00:00Z"
    },
    {
      "id": "sandbox_xyz789",
      "object": "sandbox",
      "status": "stopped",
      "public_host": "https://sandbox_xyz789.hopx.dev",
      "template_name": "python",
      "region": "eu-west",
      "created_at": "2025-01-27T12:00:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "def456",
  "request_id": "req_abc123"
}

Response Fields

Field	Type	Description
`object`	string	Always `"list"`
`data`	array	Array of sandbox objects
`has_more`	boolean	Whether more results are available
`next_cursor`	string	Cursor for the next page (if `has_more` is true)
`request_id`	string	Request ID for debugging

Each sandbox object in data includes:

id - Sandbox ID
status - Current status
public_host - VM Agent API URL
template_name - Template used
region - Deployment region
created_at - Creation timestamp

Status Codes

Code	Description
`200`	Success
`401`	Authentication required
`400`	Invalid query parameters

Pagination

Use cursor-based pagination to retrieve large result sets:

First request - Omit cursor parameter:

curl "https://api.hopx.dev/v1/sandboxes?limit=10" \
  -H "Authorization: Bearer $HOPX_API_KEY"

Check for more - If has_more is true, use next_cursor:

curl "https://api.hopx.dev/v1/sandboxes?limit=10&cursor=def456" \
  -H "Authorization: Bearer $HOPX_API_KEY"

Repeat - Continue until has_more is false

Filtering

Filter by Status

# Only running sandboxes
curl "https://api.hopx.dev/v1/sandboxes?status=running" \
  -H "Authorization: Bearer $HOPX_API_KEY"

# Only stopped sandboxes
curl "https://api.hopx.dev/v1/sandboxes?status=stopped" \
  -H "Authorization: Bearer $HOPX_API_KEY"

Filter by Region

curl "https://api.hopx.dev/v1/sandboxes?region=us-east" \
  -H "Authorization: Bearer $HOPX_API_KEY"

Combine Filters

curl "https://api.hopx.dev/v1/sandboxes?status=running&region=us-east&limit=50" \
  -H "Authorization: Bearer $HOPX_API_KEY"

Use Cases

Count Running Sandboxes

curl "https://api.hopx.dev/v1/sandboxes?status=running" \
  -H "Authorization: Bearer $HOPX_API_KEY" | jq '.data | length'

List All Sandboxes (Paginated)

#!/bin/bash
CURSOR=""
while true; do
  if [ -z "$CURSOR" ]; then
    RESPONSE=$(curl -s "https://api.hopx.dev/v1/sandboxes?limit=100" \
      -H "Authorization: Bearer $HOPX_API_KEY")
  else
    RESPONSE=$(curl -s "https://api.hopx.dev/v1/sandboxes?limit=100&cursor=$CURSOR" \
      -H "Authorization: Bearer $HOPX_API_KEY")
  fi
  
  echo "$RESPONSE" | jq '.data[]'
  
  HAS_MORE=$(echo "$RESPONSE" | jq -r '.has_more')
  if [ "$HAS_MORE" != "true" ]; then
    break
  fi
  
  CURSOR=$(echo "$RESPONSE" | jq -r '.next_cursor')
done

Find Sandboxes by Template

curl "https://api.hopx.dev/v1/sandboxes" \
  -H "Authorization: Bearer $HOPX_API_KEY" | \
  jq '.data[] | select(.template_name == "code-interpreter")'

SDK: Sandbox.list() - Python SDK method
SDK: Sandbox.iter() - Python SDK method
CLI Sandbox Commands - Manage sandboxes from CLI

Next Steps

Get Sandbox - Get details for a specific sandbox
Create Sandbox - Create a new sandbox
Delete Sandbox - Clean up unused sandboxes

Getting Started

Concepts

Control Plane API

VM Agent API

Endpoint

Request

Headers

Query Parameters

Example Request

Response

Success (200 OK)

Response Fields

Status Codes

Filtering

Filter by Status

Filter by Region

Combine Filters

Use Cases

Count Running Sandboxes

List All Sandboxes (Paginated)

Find Sandboxes by Template

Next Steps

​Endpoint

​Request

​Headers

​Query Parameters

​Example Request

​Response

​Success (200 OK)

​Response Fields

​Status Codes

​Pagination

​Filtering

​Filter by Status

​Filter by Region

​Combine Filters

​Use Cases

​Count Running Sandboxes

​List All Sandboxes (Paginated)

​Find Sandboxes by Template

​Related

​Next Steps

Endpoint

Request

Headers

Query Parameters

Example Request

Response

Success (200 OK)

Response Fields

Status Codes

Pagination

Filtering

Filter by Status

Filter by Region

Combine Filters

Use Cases

Count Running Sandboxes

List All Sandboxes (Paginated)

Find Sandboxes by Template

Related

Next Steps