> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Sandboxes

> List and filter all your sandboxes with pagination support using the HopX Control Plane API. Query sandboxes by status, region, template, or other criteria. Learn how to use GET /v1/sandboxes endpoint with filtering, pagination, and sorting options. Includes Python and JavaScript SDK examples.

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:

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

Filter by region:

```bash theme={null}
curl "https://api.hopx.dev/v1/sandboxes?region=us-east" \
  -H "Authorization: Bearer $HOPX_API_KEY"
```

Paginated request:

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

## Response

### Success (200 OK)

```json theme={null}
{
  "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:

1. **First request** - Omit `cursor` parameter:

```bash theme={null}
curl "https://api.hopx.dev/v1/sandboxes?limit=10" \
  -H "Authorization: Bearer $HOPX_API_KEY"
```

2. **Check for more** - If `has_more` is `true`, use `next_cursor`:

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

3. **Repeat** - Continue until `has_more` is `false`

## Filtering

### Filter by Status

```bash theme={null}
# 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

```bash theme={null}
curl "https://api.hopx.dev/v1/sandboxes?region=us-east" \
  -H "Authorization: Bearer $HOPX_API_KEY"
```

### Combine Filters

```bash theme={null}
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

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

### List All Sandboxes (Paginated)

```bash theme={null}
#!/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

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

## Related

* **SDK**: [Sandbox.list()](/sdk/python/sandbox#list) - Python SDK method
* **SDK**: [Sandbox.iter()](/sdk/python/sandbox#iter) - Python SDK method
* [CLI Sandbox Commands](/cli/commands/sandbox) - Manage sandboxes from CLI

## Next Steps

* **[Get Sandbox](/api/control-plane/get-sandbox)** - Get details for a specific sandbox
* **[Create Sandbox](/api/control-plane/create-sandbox)** - Create a new sandbox
* **[Delete Sandbox](/api/control-plane/delete-sandbox)** - Clean up unused sandboxes