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

# List and filter sandboxes

> List running and paused sandboxes, filter by state and metadata on the server, and page through results with the SDK or with ppio sandbox list.

`ppio.sandbox.list()` returns the sandboxes a team owns. Listing is how a program learns a sandbox ID that another process created, and it takes filters so a large set narrows on the server. Once a running sandbox is found, [connect to it](https://docs.ppio.ai/sandbox/connect.md) with `ppio.sandbox.connect()`.

> [!NOTE]
>
> Install the SDK, or the CLI for `ppio` commands, and set the `PPIO_API_KEY` and `PPIO_DOMAIN` environment variables before running these examples. See [Quickstart](https://docs.ppio.ai/sandbox/quickstart.md) and [Install and authenticate](https://docs.ppio.ai/sandbox/cli/install.md).

## List sandboxes

```python Python theme={null}
from ppio_sandbox import PPIO, SandboxQuery, SandboxState

ppio = PPIO()

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

# List all running sandboxes.
running_sandboxes_paginator = ppio.sandbox.list(
    query=SandboxQuery(
        state=[SandboxState.RUNNING],
    ),
)

running_sandboxes = running_sandboxes_paginator.next_items()

running_sandbox = running_sandboxes[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 end at:', running_sandbox.end_at)
print('Running sandbox template id:', running_sandbox.template_id)
print('Running sandbox state:', running_sandbox.state)

sandbox.kill()
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

// Create a sandbox.
const sandbox = await ppio.sandbox.create({
  metadata: {
    name: 'My Sandbox',
  },
})

// List all running sandboxes.
const runningSandboxesPaginator = await ppio.sandbox.list({
  query: {
    state: ['running'],
  },
})

const runningSandboxes = await runningSandboxesPaginator.nextItems()
const runningSandbox = runningSandboxes[0]

console.log('Running sandbox metadata:', runningSandbox.metadata)
console.log('Running sandbox id:', runningSandbox.sandboxId)
console.log('Running sandbox started at:', runningSandbox.startedAt)
console.log('Running sandbox ends at:', runningSandbox.endAt)
console.log('Running sandbox template id:', runningSandbox.templateId)
console.log('Running sandbox state:', runningSandbox.state)

await sandbox.kill()
```

```bash CLI theme={null}
# List running sandboxes (alias: sandbox ls)
ppio sandbox list

# Filter by metadata
ppio sandbox list --metadata key1=value1

# JSON output
ppio sandbox list --output json
```

## Filter by metadata

Filter sandboxes with [metadata](https://docs.ppio.ai/sandbox/create.md) key-value pairs. Specifying multiple key-value pairs returns sandboxes that match all of them. The filtering is performed on the server, which keeps a large set of sandboxes manageable.

```python Python theme={null}
from ppio_sandbox import PPIO, SandboxQuery

ppio = PPIO()

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

# List all running sandboxes that have the `user_id` key with value `123` and the `env` key with value `dev`.
paginator = ppio.sandbox.list(
    query=SandboxQuery(
        metadata={
            'user_id': '123',
            'env': 'dev',
        }
    ),
)

for running_sandbox in paginator.next_items():
    print(
        'list running sandbox (%s) metadata:' % running_sandbox.sandbox_id,
        running_sandbox.metadata,
    )

sandbox.kill()
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()

// Create a sandbox with metadata.
const sandbox = await ppio.sandbox.create({
  metadata: {
    env: 'dev',
    app: 'my-app',
    userId: '123',
  },
})

// List all running sandboxes that have the `userId` key with value `123` and the `env` key with value `dev`.
const runningSandboxesPaginator = await ppio.sandbox.list({
  query: {
    metadata: { userId: '123', env: 'dev' },
  },
})

const runningSandboxes = await runningSandboxesPaginator.nextItems()
for (const runningSandbox of runningSandboxes) {
  console.log(
    `list running sandbox (${runningSandbox.sandboxId}) metadata:`,
    runningSandbox.metadata,
  )
}

await sandbox.kill()
```

## Filter by state

The state filter accepts `running`, `paused`, or both, and returns the sandboxes in those states.

```python Python theme={null}
from ppio_sandbox import PPIO, SandboxQuery, SandboxState

ppio = PPIO()
sandbox = ppio.sandbox.create()

# List all sandboxes that are running or paused.
paginator = ppio.sandbox.list(
    query=SandboxQuery(
        state=[SandboxState.RUNNING, SandboxState.PAUSED],
    ),
)

# Get the first page of sandboxes (running and paused)
sandboxes = paginator.next_items()

sandbox.kill()
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()

// List all sandboxes that are running or paused.
const paginator = await ppio.sandbox.list({
  query: {
    state: ['running', 'paused'],
  },
})

const sandboxes = await paginator.nextItems()

await sandbox.kill()
```

## Page through results

`ppio.sandbox.list()` returns a paginator. `next_items()` / `nextItems()` returns one page of sandboxes, running and paused.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create()

# List all sandboxes (running and paused)
paginator = ppio.sandbox.list()

first_page = paginator.next_items()
if paginator.has_next:
    next_page = paginator.next_items()

sandbox.kill()
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()
const paginator = await ppio.sandbox.list()

// Get the first page of sandboxes (running and paused)
const firstPage = await paginator.nextItems()
if (paginator.hasNext) {
  // Get the next page of sandboxes
  const nextPage = await paginator.nextItems()
}

await sandbox.kill()
```

### Set the page size

For finer control over pagination, pass the number of items to return per page with `limit`, and pass `nextToken` or `next_token` to start from a known position.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create()

paginator = ppio.sandbox.list(
    limit=100,
    # next_token='',
)

# Fetch the next page
paginator.next_items()

# Whether there is a next page
print('paginator.has_next: ', paginator.has_next)

# Next page offset parameter
print('paginator.next_token: ', paginator.next_token)

sandbox.kill()
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()

const paginator = await ppio.sandbox.list({
  limit: 100,
  // nextToken: '',
})

// Fetch the next page
await paginator.nextItems()

// Additional paginator properties
// Whether there is a next page
console.log('paginator.hasNext: ', paginator.hasNext)

// Next page token
console.log('paginator.nextToken: ', paginator.nextToken)

await sandbox.kill()
```

### Retrieve all pages

To retrieve all pages, iterate the paginator. `has_next` / `hasNext` is initially true before the first page is fetched and becomes false after the last page is returned.

```python Python theme={null}
from ppio_sandbox import PPIO, SandboxInfo

ppio = PPIO()
sandbox = ppio.sandbox.create()

paginator = ppio.sandbox.list()

# Get all sandboxes
sandboxes: list[SandboxInfo] = []
while paginator.has_next:
    items = paginator.next_items()
    sandboxes.extend(items)

sandbox.kill()
```

```javascript Node.js theme={null}
import { PPIO, SandboxInfo } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()
const paginator = await ppio.sandbox.list()

const sandboxes: SandboxInfo[] = []
while (paginator.hasNext) {
  const items = await paginator.nextItems()
  sandboxes.push(...items)
}

for (const sandbox of sandboxes) {
  console.log(`list sandbox (${sandbox.sandboxId})`)
}

await sandbox.kill()
```

## List options

> [tab] Python
>
> **query** `SandboxQuery`
>
> Filter conditions.
>
> **properties**
>
> **metadata**
>
> Matches key-value pairs.
>
> **state**
>
> One or both of `SandboxState.RUNNING` and `SandboxState.PAUSED`.
>
> **limit** `int`
>
> Number of items to return per page. Optional.
>
> **next\_token** `string`
>
> Position where pagination starts. Optional.

> [tab] Node.js
>
> **query** `object`
>
> Filter conditions.
>
> **properties**
>
> **metadata**
>
> Matches key-value pairs.
>
> **state**
>
> One or both of `'running'` and `'paused'`.
>
> **limit** `number`
>
> Number of items to return per page. Optional.
>
> **nextToken** `string`
>
> Position where pagination starts. Optional.

## Paginator fields

> [tab] Python
>
> **next\_items()** `List[SandboxInfo]`
>
> Returns one page of sandboxes, running and paused.
>
> **has\_next** `bool`
>
> `True` before the first page is fetched, and `False` after the last page is returned.
>
> **next\_token** `Optional[str]`
>
> Position where the next page starts.

> [tab] Node.js
>
> **nextItems()** `Promise\<SandboxInfo[]\>`
>
> Returns one page of sandboxes, running and paused.
>
> **hasNext** `boolean`
>
> `true` before the first page is fetched, and `false` after the last page is returned.
>
> **nextToken** `string | undefined`
>
> Position where the next page starts.


## Related topics

- [Configure an idle timeout](https://docs.ppio.ai/sandbox/idle-timeout.md)
- [Manage sandboxes in the PPIO console](https://docs.ppio.ai/sandbox/console.md)
- [Save and restore sandbox state with snapshots](https://docs.ppio.ai/sandbox/snapshots.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.