# List sandboxes - Documentation

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown is available with `Accept: text/markdown` and `.md` URL variants.

Source: /docs/guides/sandbox-list

# List sandboxes

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

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

JavaScript & TypeScript

Python

```
import { Sandbox } from 'novita-sandbox/code-interpreter'

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

// List all running sandboxes.
const runningSandboxesPaginator = await 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()
```

```
from novita_sandbox.code_interpreter import Sandbox, SandboxQuery, SandboxState

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

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

##

[​](#filtering-sandboxes)

Filtering sandboxes

You can filter sandboxes by specifying [Metadata](/docs/guides/sandbox-metadata) 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.

JavaScript & TypeScript

Python

```
import { Sandbox } from 'novita-sandbox/code-interpreter'

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

```
from novita_sandbox.code_interpreter import Sandbox, SandboxQuery

# Create sandbox with metadata.
sandbox = 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 = Sandbox.list(
query=SandboxQuery(
metadata={
"user_id": "123",
"env": "dev",
}
),
)

sandbox.kill()
```

###

[​](#listing-sandboxes)

Listing sandboxes

Pagination is now supported by the `Sandbox.list()` method. To learn more about pagination techniques with the updated method, refer to the [advanced pagination](#advanced-pagination) section.

JavaScript & TypeScript

Python

```
import { Sandbox } from 'novita-sandbox/code-interpreter'

const sandbox = await Sandbox.create()

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

```
from novita_sandbox.code_interpreter import Sandbox

sandbox = Sandbox.create()

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

firstPage = paginator.next_items()
if paginator.has_next:
nextPage = paginator.next_items()

sandbox.kill()
```

###

[​](#filtering-sandboxes-2)

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.

JavaScript & TypeScript

Python

```
import { Sandbox } from 'novita-sandbox/code-interpreter'

const sandbox = await Sandbox.create()

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

const sandboxes = await paginator.nextItems()

await sandbox.kill()
```

```
from novita_sandbox.code_interpreter import Sandbox, SandboxQuery, SandboxState

sandbox = Sandbox.create()

# List all sandboxes that are running or paused.
paginator = 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.

JavaScript & TypeScript

Python

```
import { Sandbox } from 'novita-sandbox/code-interpreter'

// Create sandbox with metadata.
const sandbox = await 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 = Sandbox.list({
query: {
metadata: { userId: '123', env: 'dev' },
},
})

const sandboxes = await paginator.nextItems()

await sandbox.kill()
```

```
from novita_sandbox.code_interpreter import Sandbox, SandboxQuery

# Create sandbox with metadata.
sandbox = 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 = Sandbox.list(
query=SandboxQuery(
metadata={
"user_id": "123",
"env": "dev",
}
),
)

sandboxes = paginator.next_items()

sandbox.kill()
```

###

[​](#advanced-pagination)

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.

JavaScript & TypeScript

Python

```
import { Sandbox } from 'novita-sandbox/code-interpreter'

const sandbox = await Sandbox.create()

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

```
from novita_sandbox.code_interpreter import Sandbox

sandbox = Sandbox.create()

paginator = 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.

JavaScript & TypeScript

Python

```
import { Sandbox, SandboxInfo } from 'novita-sandbox/code-interpreter'

const sandbox = await Sandbox.create()

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

```
from novita_sandbox.code_interpreter import Sandbox, SandboxInfo

sandbox = Sandbox.create()

paginator = Sandbox.list()

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

sandbox.kill()
```

Last modified on June 24, 2026