# List Query
<subtitle>Retrieve and filter sandbox instances currently in running or paused state.</subtitle>

## Environment Setup

Before using the SDK, please ensure that the `AGENTBOX_API_KEY` environment variable is configured.

>
> You can obtain your API key from the [Console API Keys page](https://console.ucloud.cn/modelverse/experience/api-keys).

```bash
export AGENTBOX_API_KEY=your_api_key
```

Through the `Sandbox.list()` method, you can easily get a list of all active sandboxes under your account, and support fine-grained filtering and pagination by state and metadata.

## Basic Query

`Sandbox.list()` returns a paginator object.

```python
from ucloud_sandbox import Sandbox

# Get paginator
paginator = Sandbox.list()

# Get first page data (default includes running and paused sandboxes)
first_page = paginator.next_items()

for sbx in first_page:
    print(f"ID: {sbx.sandbox_id} | Template: {sbx.template_id} | Status: {sbx.state}")
```

## Filter by Conditions

### Filter by Task State
You can query only `RUNNING` (running) or `PAUSED` (paused) sandboxes.

```python
from ucloud_sandbox import Sandbox, SandboxQuery, SandboxState

# Query only sandboxes in paused state
paginator = Sandbox.list(
    query=SandboxQuery(
        state=[SandboxState.PAUSED],
    ),
)
sandboxes = paginator.next_items()
```

### Filter by Custom Metadata
If you attached `metadata` when creating sandboxes, you can retrieve specific sandboxes through these tags.

```python
from ucloud_sandbox import Sandbox, SandboxQuery

# Find sandboxes with user_id "123" and environment "dev"
paginator = Sandbox.list(
    query=SandboxQuery(
        metadata={
            "user_id": "123",
            "env": "dev"
        }
    ),
)
sandboxes = paginator.next_items()
```

## Pagination

>
> **Limit Note**: The maximum limit for a single query is **100**.

### Manual Pagination
Use `next_token` for pagination operations.

```python
paginator = Sandbox.list(limit=50)

# Check if there is more data
if paginator.has_next:
    print(f"Next Token: {paginator.next_token}")
    # Get next page
    next_items = paginator.next_items()
```

### Automatically Get All Data
Load all active sandboxes at once through loop processing.

```python
paginator = Sandbox.list()
all_sandboxes = []

while paginator.has_next:
    items = paginator.next_items()
    all_sandboxes.extend(items)

print(f"Total active sandboxes: {len(all_sandboxes)}")
```

## Next Steps

After obtaining the sandbox ID, you can:
- Call `Sandbox.connect(id)` to [reconnect to sandbox](/docs/agent-sandbox/sdk/sandbox/09-connect-to-running-sandbox).
- Call `Sandbox.kill(id)` to force shutdown.
- Retrieve its runtime metrics.