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

# List sandboxes

You can use the `novita.sandbox.list()` method to list sandboxes.

Once you have information about a running sandbox, you can [connect](/guides/sandbox-connect) to it using the `novita.sandbox.connect()` method.

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita, SandboxState } from 'novita-sandbox'

const novita = new Novita()

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

// List all running sandboxes.
const runningSandboxesPaginator = await novita.sandbox.list({
  query: {
    state: [SandboxState.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()
```

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita, SandboxQuery, SandboxState

novita = Novita()

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

# List all running sandboxes.
running_sandboxes_paginator = novita.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()
```

```bash CLI icon="terminal" theme={"system"}
# List running sandboxes (alias: sandbox ls)
novita sandbox list

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

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

## Filtering sandboxes

You can filter sandboxes by specifying [Metadata](/guides/sandbox-create) key-value pairs.

Specifying multiple key-value pairs returns sandboxes that match all of them.

This can be useful when you have a large number of sandboxes and want to find only specific ones. The filtering is performed on the server.

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita } from 'novita-sandbox'

const novita = new Novita()

// Create a sandbox with metadata.
const sandbox = await novita.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 novita.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()
```

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita, SandboxQuery

novita = Novita()

# Create sandbox with metadata.
sandbox = novita.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 = novita.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()
```

### Listing sandboxes

Pagination is now supported by the `novita.sandbox.list()` method. To learn more about pagination techniques with the updated method, refer to the advanced pagination section.

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita } from 'novita-sandbox'

const novita = new Novita()
const sandbox = await novita.sandbox.create()
const paginator = await novita.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()
```

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita

novita = Novita()
sandbox = novita.sandbox.create()

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

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

sandbox.kill()
```

### Filtering sandboxes

You can filter sandboxes based on their current status. The state parameter accepts `running`, `paused`, or both to return sandboxes in the specified states.

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita, SandboxState } from 'novita-sandbox'

const novita = new Novita()
const sandbox = await novita.sandbox.create()

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

const sandboxes = await paginator.nextItems()

await sandbox.kill()
```

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita, SandboxQuery, SandboxState

novita = Novita()
sandbox = novita.sandbox.create()

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

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

sandbox.kill()
```

You can specify metadata key-value pairs during sandbox creation and later use them when listing sandboxes.

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita } from 'novita-sandbox'

const novita = new Novita()

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

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

const sandboxes = await paginator.nextItems()

await sandbox.kill()
```

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita, SandboxQuery

novita = Novita()

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

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

sandboxes = paginator.next_items()

sandbox.kill()
```

### Advanced pagination

For finer control over pagination, specify the number of items to return per page (the default and maximum is 100) and provide an offset parameter (`nextToken` or `next_token`) to indicate where pagination should begin.

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita } from 'novita-sandbox'

const novita = new Novita()
const sandbox = await novita.sandbox.create()

const paginator = await novita.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()
```

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita

novita = Novita()
sandbox = novita.sandbox.create()

paginator = novita.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()
```

You can retrieve all pages by iterating through the paginator. `hasNext` / `has_next` is initially true before the first page is fetched and becomes false after the last page is returned.

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita, SandboxInfo } from 'novita-sandbox'

const novita = new Novita()
const sandbox = await novita.sandbox.create()
const paginator = await novita.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()
```

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita, SandboxInfo

novita = Novita()
sandbox = novita.sandbox.create()

paginator = novita.sandbox.list()

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

sandbox.kill()
```


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