Skip to main content
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

ParameterTypeRequiredDescription
limitintegerNoMaximum number of results (default: 100, max: 1000)
statusstringNoFilter by status: running, stopped, paused, creating
regionstringNoFilter by region (e.g., us-east, eu-west)
cursorstringNoPagination 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

FieldTypeDescription
objectstringAlways "list"
dataarrayArray of sandbox objects
has_morebooleanWhether more results are available
next_cursorstringCursor for the next page (if has_more is true)
request_idstringRequest 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

CodeDescription
200Success
401Authentication required
400Invalid query parameters

​
Pagination

Use cursor-based pagination to retrieve large result sets:
  1. First request - Omit cursor parameter:
curl "https://api.hopx.dev/v1/sandboxes?limit=10" \
  -H "Authorization: Bearer $HOPX_API_KEY"
  1. 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"
  1. 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")'

​
Next Steps