> ## 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.

# Listing

> List and filter your sandboxes by status, region, template, and other criteria. Discover how to query existing sandboxes, filter by status or region, iterate through sandbox lists, and find specific sandboxes using Python and JavaScript SDKs or REST API endpoints. Includes pagination and filtering examples.

List and filter your sandboxes to find existing environments, monitor their status, and manage multiple sandboxes efficiently.

## Prerequisites

Before you begin, make sure you have:

* **HopX API key** - Get one from [console.hopx.dev](https://console.hopx.dev) or see \[API key Management]\(/API key)
* **SDK installed** - Python SDK (`pip install hopx-ai`) or JavaScript SDK (`npm install @hopx-ai/sdk`)
* **At least one sandbox** - You should have created at least one sandbox (see [Creating Sandboxes](/core-concepts/sandboxes/creating))

## Basic Listing

List all your sandboxes:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox

    # List all sandboxes
    sandboxes = Sandbox.list()

    print(f"Found {len(sandboxes)} sandboxes")
    for sandbox in sandboxes:
        info = sandbox.get_info()
        print(f"{sandbox.sandbox_id}: {info.status}")
    ```

    **Expected Output:**

    ```
    Found 3 sandboxes
    sandbox_abc123xyz: running
    sandbox_def456uvw: paused
    sandbox_ghi789rst: running
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

    // List all sandboxes
    const sandboxes = await Sandbox.list();

    console.log(`Found ${sandboxes.length} sandboxes`);
    for (const sandbox of sandboxes) {
      const info = await sandbox.getInfo();
      console.log(`${sandbox.sandboxId}: ${info.status}`);
    }
    ```

    **Expected Output:**

    ```
    Found 3 sandboxes
    sandbox_abc123xyz: running
    sandbox_def456uvw: paused
    sandbox_ghi789rst: running
    ```
  </Tab>
</Tabs>

## Filtering by Status

Filter sandboxes by their current status:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox

    # List only running sandboxes
    running = Sandbox.list(status="running")
    print(f"Running sandboxes: {len(running)}")

    # List paused sandboxes
    paused = Sandbox.list(status="paused")
    print(f"Paused sandboxes: {len(paused)}")
    ```

    **Expected Output:**

    ```
    Running sandboxes: 2
    Paused sandboxes: 1
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

    // List only running sandboxes
    const running = await Sandbox.list({ status: 'running' });
    console.log(`Running sandboxes: ${running.length}`);

    // List paused sandboxes
    const paused = await Sandbox.list({ status: 'paused' });
    console.log(`Paused sandboxes: ${paused.length}`);
    ```

    **Expected Output:**

    ```
    Running sandboxes: 2
    Paused sandboxes: 1
    ```
  </Tab>
</Tabs>

## Combining Filters

Combine multiple filters:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox

    # List running sandboxes in EU region
    running_eu = Sandbox.list(status="running", region="eu-west")
    print(f"Running EU sandboxes: {len(running_eu)}")

    # List with limit
    limited = Sandbox.list(status="running", limit=10)
    print(f"First 10 running sandboxes: {len(limited)}")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

    // List running sandboxes in EU region
    const runningEu = await Sandbox.list({
      status: 'running',
      region: 'eu-west'
    });
    console.log(`Running EU sandboxes: ${runningEu.length}`);

    // List with limit
    const limited = await Sandbox.list({
      status: 'running',
      limit: 10
    });
    console.log(`First 10 running sandboxes: ${limited.length}`);
    ```
  </Tab>
</Tabs>

## Lazy Iteration (Python)

For better memory usage with many sandboxes, use the iterator:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox

    found_it_flag = False

    # Lazy loading - fetches pages as needed
    for sandbox in Sandbox.iter(status="running"):
        info = sandbox.get_info()
        print(f"{sandbox.sandbox_id}: {info.public_host}")
        
        # Can break early without fetching remaining pages
        if found_it_flag:
            break
    ```
  </Tab>
</Tabs>

<Note>
  The `iter()` method is more memory-efficient for large numbers of sandboxes because it fetches pages on-demand rather than loading all sandboxes into memory at once.
</Note>

## Getting Detailed Information

Get detailed information for each sandbox:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox

    sandboxes = Sandbox.list(status="running")

    for sandbox in sandboxes:
        info = sandbox.get_info()
        print(f"\nSandbox: {sandbox.sandbox_id}")
        print(f"  Status: {info.status}")
        print(f"  Template: {info.template_name}")
        print(f"  URL: {info.public_host}")
        print(f"  Resources: {info.vcpu} vCPU, {info.memory_mb}MB RAM")
        print(f"  Internet: {info.internet_access}")
        if info.expires_at:
            print(f"  Expires: {info.expires_at}")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

    const sandboxes = await Sandbox.list({ status: 'running' });

    for (const sandbox of sandboxes) {
      const info = await sandbox.getInfo();
      console.log(`\nSandbox: ${sandbox.sandboxId}`);
      console.log(`  Status: ${info.status}`);
      console.log(`  Template: ${info.templateName}`);
      console.log(`  URL: ${info.publicHost}`);
      console.log(`  Resources: ${info.vcpu} vCPU, ${info.memoryMb}MB RAM`);
      console.log(`  Internet: ${info.internetAccess}`);
      if (info.expiresAt) {
        console.log(`  Expires: ${info.expiresAt}`);
      }
    }
    ```
  </Tab>
</Tabs>

## Common Use Cases

### Find a Specific Sandbox

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox

    # Find sandbox by ID pattern
    sandboxes = Sandbox.list()
    target_id = "1763309903rt5vs4lm"

    for sandbox in sandboxes:
        if sandbox.sandbox_id == target_id:
            print(f"Found: {sandbox.sandbox_id}")
            info = sandbox.get_info()
            print(f"Status: {info.status}")
            break
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

    // Find sandbox by ID pattern
    const sandboxes = await Sandbox.list();
    const targetId = '1763309903rt5vs4lm';

    for (const sandbox of sandboxes) {
      if (sandbox.sandboxId === targetId) {
        console.log(`Found: ${sandbox.sandboxId}`);
        const info = await sandbox.getInfo();
        console.log(`Status: ${info.status}`);
        break;
      }
    }
    ```
  </Tab>
</Tabs>

### Count Sandboxes by Status

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox
    from collections import Counter

    # Count sandboxes by status
    sandboxes = Sandbox.list()
    status_counts = Counter(sb.get_info().status for sb in sandboxes)

    print("Sandbox status summary:")
    for status, count in status_counts.items():
        print(f"  {status}: {count}")
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

    // Count sandboxes by status
    const sandboxes = await Sandbox.list();
    const statusCounts = {};

    for (const sandbox of sandboxes) {
      const info = await sandbox.getInfo();
      statusCounts[info.status] = (statusCounts[info.status] || 0) + 1;
    }

    console.log('Sandbox status summary:');
    for (const [status, count] of Object.entries(statusCounts)) {
      console.log(`  ${status}: ${count}`);
    }
    ```
  </Tab>
</Tabs>

### Clean Up Old Sandboxes

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from hopx_ai import Sandbox
    from datetime import datetime, timedelta

    # Find and clean up sandboxes older than 1 hour
    sandboxes = Sandbox.list()
    cutoff = datetime.now() - timedelta(hours=1)

    for sandbox in sandboxes:
        info = sandbox.get_info()
        created = datetime.fromisoformat(info.created_at.replace('Z', '+00:00'))
        
        if created < cutoff:
            print(f"Cleaning up old sandbox: {sandbox.sandbox_id}")
            sandbox.kill()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    import { Sandbox } from '@hopx-ai/sdk';

    // Find and clean up sandboxes older than 1 hour
    const sandboxes = await Sandbox.list();
    const cutoff = new Date(Date.now() - 60 * 60 * 1000); // 1 hour ago

    for (const sandbox of sandboxes) {
      const info = await sandbox.getInfo();
      const created = new Date(info.createdAt);
      
      if (created < cutoff) {
        console.log(`Cleaning up old sandbox: ${sandbox.sandboxId}`);
        await sandbox.kill();
      }
    }
    ```
  </Tab>
</Tabs>

## API Direct Access

You can also list sandboxes using direct API calls:

```bash theme={null}
# List all sandboxes
curl https://api.hopx.dev/v1/sandboxes \
  -H "Authorization: Bearer your-API key"

# Filter by status
curl "https://api.hopx.dev/v1/sandboxes?status=running" \
  -H "Authorization: Bearer your-API key"

# Filter by region
curl "https://api.hopx.dev/v1/sandboxes?region=eu-west" \
  -H "Authorization: Bearer your-API key"

# Combine filters
curl "https://api.hopx.dev/v1/sandboxes?status=running&region=us-east&limit=10" \
  -H "Authorization: Bearer your-API key"
```

## Implementation

* **SDK**: [Sandbox.list()](/sdk/python/sandbox#list) - Python SDK method
* **[CLI](/cli/introduction)** - Command-line interface
* **SDK**: [Sandbox.iter()](/sdk/python/sandbox#iter) - Python SDK iterator method
* **API**: [GET /v1/sandboxes](/api/control-plane/list-sandboxes) - Control Plane API endpoint

## Related

* **[Creating Sandboxes](/core-concepts/sandboxes/creating)** - Create new sandboxes
* **[Connecting to Sandboxes](/core-concepts/sandboxes/connecting)** - Connect to existing sandboxes
* **[Managing Sandbox State](/core-concepts/sandboxes/managing-state)** - Control sandbox lifecycle
* **[API Pagination](/api/concepts/pagination)** - Understand pagination in list results

## Next Steps

* Learn about [Connecting to Existing](/core-concepts/sandboxes/connecting) sandboxes from the list
* Understand [Managing State](/core-concepts/sandboxes/managing-state) operations
* Explore [Timeout Management](/core-concepts/sandboxes/timeout) for listed sandboxes