import Link from 'next/link'

# List sandboxes

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

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

<CodeGroup>
```js
import { Sandbox } from '@e2b/code-interpreter'

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

// List all running sandboxes.
const runningSandboxes = await Sandbox.list() // $HighlightLine
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 template id:', runningSandbox.templateId)
```
```python
from e2b_code_interpreter import Sandbox

# Create a sandbox.
sandbox = Sandbox({
  metadata: {
    name: 'My Sandbox',
  },
})

# List all running sandboxes.
running_sandboxes = Sandbox.list() # $HighlightLine
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 template id:', running_sandbox.template_id)
```
</CodeGroup>

The code above will output something like this:
<CodeGroup isTerminalCommand>
```bash {{ language: "js" }}
Running sandbox metadata: {
  name: "My Sandbox",
}
Running sandbox id: ixjj3iankaishgcge4jwn-b0b684e9
Running sandbox started at: 2024-10-15T21:13:07.311Z
Running sandbox template id: 3e4rngfa34txe0gxc1zf
```
```bash {{ language: "python" }}
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
```
</CodeGroup>


## Filtering sandboxes

You can filter sandboxes by specifying <Link href="/docs/sandbox/metadata">Metadata</Link> key value pairs.
Specifying multiple key value pairs will return 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.

<CodeGroup>
```js
import { Sandbox } from '@e2b/code-interpreter'

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

// List running sandboxes that has `userId` key with value `123` and `env` key with value `dev`.
const runningSandboxes = await Sandbox.list({
  query: {
    metadata: { userId: '123', env: 'dev' }, // $HighlightLine
  },
})
```
```python
from e2b_code_interpreter import Sandbox
from e2b.sandbox.sandbox_api import SandboxQuery

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

# List running sandboxes that has `userId` key with value `123` and `env` key with value `dev`.
running_sandboxes = Sandbox.list(
    query=SandboxQuery(
        metadata={
            "userId": "123",  # $HighlightLine
            "env": "dev",  # $HighlightLine
        }
    ),
)
```
</CodeGroup>

## Changes in the Beta SDKs

<Note>
If you're using the [beta version of the SDK](/docs/sandbox/installing-beta-sdks), the `Sandbox.list()` method was updated.
</Note>

### Listing sandboxes

The `Sandbox.list()` method now supports pagination. In the [advanced pagination](/docs/sandbox/list#advanced-pagination) section, you can find more information about pagination techniques using the updated method.

<CodeGroup>
```js
import { Sandbox, SandboxInfo } from '@e2b/code-interpreter'

const sandbox = await Sandbox.create()

const paginator = Sandbox.list() // $HighlightLine

// Get the first page of sandboxes (running and paused)
const firstPage = await paginator.nextItems() // $HighlightLine

// Get the next page of sandboxes
const nextPage = await paginator.nextItems() // $HighlightLine
```
```python
from e2b_code_interpreter import Sandbox, SandboxInfo

sandbox = Sandbox()

paginator = Sandbox.list() # $HighlightLine

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

# Get the next page of sandboxes
nextPage = paginator.next_items() # $HighlightLine
```
</CodeGroup>


### Filtering sandboxes

Filter sandboxes by their current state. The state parameter can contain either "**running**" for running sandboxes or "**paused**" for paused sandboxes, or both.

<CodeGroup>
```js
import { Sandbox } from '@e2b/code-interpreter'

// Create a sandbox.
const sandbox = await Sandbox.create()

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

const sandboxes = await paginator.nextItems() // $HighlightLine
```
```python
from e2b_code_interpreter import Sandbox, SandboxListQuery

# Create a sandbox with metadata.
sandbox = Sandbox()

# List running sandboxes that are running or paused.
paginator = Sandbox.list(
    query=SandboxListQuery(
        state=['running', 'paused'], # $HighlightLine
    ),
)

# Get the first page of sandboxes (running and paused)
sandboxes = paginator.next_items() # $HighlightLine
```
</CodeGroup>

Filter sandboxes by the metadata key value pairs specified during Sandbox creation.

<CodeGroup>
```js
import { Sandbox } from '@e2b/code-interpreter'

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

// List all sandboxes that has `userId` key with value `123` and `env` key with value `dev`.
const paginator = Sandbox.list({
  query: {
    metadata: { userId: '123', env: 'dev' }, // $HighlightLine
  },
})

const sandboxes = await paginator.nextItems() // $HighlightLine
```
```python
from e2b_code_interpreter import Sandbox, SandboxListQuery

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

# List running sandboxes that has `userId` key with value `123` and `env` key with value `dev`.
paginator = Sandbox.list(
    query=SandboxListQuery(
        metadata={
            "userId": "123",  # $HighlightLine
            "env": "dev",  # $HighlightLine
        }
    ),
)

# Get the first page of sandboxes (running and paused)
sandboxes = paginator.next_items() # $HighlightLine
```
</CodeGroup>

### Advanced pagination

For more granular pagination, you can set custom per-page item limit (default and maximum is **1000**) and specify an offset parameter (`nextToken` or `next_token`) to start paginating from.

<CodeGroup>
```js
import { Sandbox } from '@e2b/code-interpreter'

const paginator = Sandbox.list({
  limit: 1000, // $HighlightLine
  nextToken: '<base64-encoded-token>', // $HighlightLine
})

// Additional paginator properties
// Whether there is a next page
paginator.hasNext

// Next page token
paginator.nextToken

// Fetch the next page
await paginator.nextItems()
```
```python
from e2b_code_interpreter import Sandbox, SandboxListQuery

paginator = Sandbox.list(
    limit=1000, # $HighlightLine
    next_token='<base64-encoded-token>', # $HighlightLine
)

# Additional paginator properties
# Whether there is a next page
paginator.has_next

# Next page token
paginator.next_token

# Fetch the next page
paginator.next_items()
```
</CodeGroup>

You can fetch all pages by looping through the paginator while checking if there is a next page (using `hasNext` or `has_next` property) and fetching until there are no more pages left to fetch:

<CodeGroup>
```js
import { Sandbox } from '@e2b/code-interpreter'

const paginator = Sandbox.list()

// Loop through all pages
const sandboxes: SandboxInfo[] = []
while (paginator.hasNext) { // $HighlightLine
  const items = await paginator.nextItems()
  sandboxes.push(...items)
}
```
```python
from e2b_code_interpreter import Sandbox, SandboxListQuery

paginator = Sandbox.list()

# Loop through all pages
sandboxes: list[SandboxInfo] = []
while paginator.has_next: # $HighlightLine
    items = paginator.next_items()
    sandboxes.extend(items)
```
</CodeGroup>
