# List sandboxes
<subtitle>Use `Sandbox.list()` to list sandboxes and filter by status or metadata. </subtitle>

You can list sandboxes using the `Sandbox.list()` method.

> After obtaining the running or suspended sandbox information, you can use `Sandbox.connect()` to reconnect. For more instructions, please refer to [Manual connection to running sandbox](/docs/agent-sandbox/sandbox/connect.md).

## List sandboxes

The `Sandbox.list()` method supports paging. For more paging tips, please refer to [Advanced Pagination](#Advanced Pagination).

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create(
    metadata={
        "name": "My Sandbox",
    },
)

paginator = Sandbox.list()

# Get the first page of sandboxes, including running and suspended sandboxes
first_page = paginator.next_items()

running_sandbox = first_page[0]

print("Running sandbox metadata:", running_sandbox.metadata)
print("Running sandbox id:", running_sandbox.sandbox_id)
print("Running sandbox started at:", running_sandbox.started_at)
print("Running sandbox template id:", running_sandbox.template_id)

# Get the next page sandbox
next_page = paginator.next_items()
```

The above code will output something like:

```text
Running sandbox metadata: {'name': 'My Sandbox'}
Running sandbox id: ixjj3iankaishgcge4jwn-b0b684e9
Running sandbox started at: 2024-10-15 21:13:07.311861+00:00
Running sandbox template id: 3e4rngfa34txe0gxc1zf
```

## Filter sandbox

You can filter by the current status of the sandbox. The `state` parameter can contain `running`, `paused`, or both.

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

# Create a sandbox
sandbox = Sandbox.create()

# List running or paused sandboxes
paginator = Sandbox.list(
    query=SandboxQuery(
        state=[SandboxState.RUNNING, SandboxState.PAUSED],
    ),
)

# Get the first page of sandboxes, including running and suspended sandboxes
sandboxes = paginator.next_items()
```

You can also filter by the metadata key-value pairs specified when creating the sandbox.

```python
from ucloud_sandbox import Sandbox, SandboxQuery

# Create a sandbox with metadata
sandbox = Sandbox.create(
    metadata={
        "env": "dev",
        "app": "my-app",
        "user_id": "123",
    },
)

# List the sandboxes with user_id 123 and env dev
paginator = Sandbox.list(
    query=SandboxQuery(
        metadata={
            "user_id": "123",
            "env": "dev",
        },
    ),
)

# Get the first page of sandboxes, including running and suspended sandboxes
sandboxes = paginator.next_items()
```

When multiple metadata key-value pairs are specified, only all matching sandboxes will be returned. For more metadata descriptions, please refer to [Metadata Management](/docs/agent-sandbox/sandbox/metadata.md).

## Advanced paging

If you need more fine-grained paging control, you can set the number of pages per page `limit`, and specify the offset parameter `next_token` as the starting point of paging. The default and maximum number of single pages is **100**.

```python
from ucloud_sandbox import Sandbox

paginator = Sandbox.list(
    limit=100,
    next_token="<base64-encoded-token>",
)

# Is there a next page?
paginator.has_next

# next page token
paginator.next_token

# Get the next page
paginator.next_items()
```

You can also check `has_next` in a loop and keep getting the next page until there are no more paginations.

```python
from ucloud_sandbox import Sandbox

paginator = Sandbox.list()

# Traverse all pages
sandboxes = []
while paginator.has_next:
    items = paginator.next_items()
    sandboxes.extend(items)
```