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

# List sandboxes

> List running and paused sandboxes with Sandbox.list() in the E2B SDK, filter them by state, metadata, template, or start time, sort, and paginate.

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

> [!NOTE]
>
> Once you have information about a running sandbox, you can [connect](https://docs.e2b.dev/sandbox/connect.md) to it using the `Sandbox.connect()` method.

### Listing sandboxes

The `Sandbox.list()` method supports pagination. In the [advanced pagination](https://docs.e2b.dev/sandbox/list.md#advanced-pagination) section, you can find more information about pagination techniques.

```js JavaScript & TypeScript highlight={6,11,14,24-26} theme={"theme":"css-variables"}
import { Sandbox } from 'e2b'

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

const paginator = Sandbox.list()

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

const runningSandbox = firstPage[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)

// Get the next page of sandboxes
if (paginator.hasNext) {
  const nextPage = await paginator.nextItems()
}
```

```python Python highlight={5,9,12,22-23} theme={"theme":"css-variables"}
from e2b import Sandbox, SandboxInfo

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

paginator = Sandbox.list()

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

running_sandbox = firstPage[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 of sandboxes
if paginator.has_next:
    nextPage = paginator.next_items()
```

The code above will output something like this:

```bash JavaScript & TypeScript theme={"theme":"css-variables"}
Running sandbox metadata: {name: "My Sandbox"}
Running sandbox id: ixjj3iankaishgcge4jwn
Running sandbox started at: 2024-10-15T21:13:07.311Z
Running sandbox template id: 3e4rngfa34txe0gxc1zf
```

```bash Python theme={"theme":"css-variables"}
Running sandbox metadata: {'name': 'My Sandbox'}
Running sandbox id: ixjj3iankaishgcge4jwn
Running sandbox started at: 2024-10-15 21:13:07.311861+00:00
Running sandbox template id: 3e4rngfa34txe0gxc1zf
```

### 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.

```js JavaScript & TypeScript highlight={9,13} theme={"theme":"css-variables"}
import { Sandbox } from 'e2b'

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

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

const sandboxes = await paginator.nextItems()
```

```python Python highlight={9,14} theme={"theme":"css-variables"}
from e2b import Sandbox, SandboxQuery, SandboxState

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

# List 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()
```

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

```js JavaScript & TypeScript highlight={6-8,15,18} theme={"theme":"css-variables"}
import { Sandbox } from 'e2b'

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

// 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' },
  },
})

const sandboxes = await paginator.nextItems()
```

```python Python highlight={6-8,16-17} theme={"theme":"css-variables"}
from e2b import Sandbox, SandboxQuery, SandboxState

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

# List sandboxes that have a `userId` key with value `123` and an `env` key with value `dev`.
paginator = Sandbox.list(
    query=SandboxQuery(
        metadata={
            "userId": "123",
            "env": "dev",
        }
    ),
)

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

Filter sandboxes by the template they were created from, using a template ID or alias.

```js JavaScript & TypeScript highlight={5} theme={"theme":"css-variables"}
import { Sandbox } from 'e2b'

const paginator = Sandbox.list({
  query: {
    template: 'base',
  },
})

const sandboxes = await paginator.nextItems()
```

```python Python highlight={5} theme={"theme":"css-variables"}
from e2b import Sandbox, SandboxQuery

paginator = Sandbox.list(
    query=SandboxQuery(
        template="base",
    ),
)

sandboxes = paginator.next_items()
```

Filter sandboxes by their start time. Only sandboxes started at or after the given timestamp are returned.

```js JavaScript & TypeScript highlight={5} theme={"theme":"css-variables"}
import { Sandbox } from 'e2b'

const paginator = Sandbox.list({
  query: {
    startedAfter: new Date('2025-01-01T00:00:00Z'),
  },
})

const sandboxes = await paginator.nextItems()
```

```python Python highlight={6} theme={"theme":"css-variables"}
from datetime import datetime, timezone
from e2b import Sandbox, SandboxQuery

paginator = Sandbox.list(
    query=SandboxQuery(
        started_after=datetime(2025, 1, 1, tzinfo=timezone.utc),
    ),
)

sandboxes = paginator.next_items()
```

### Sorting sandboxes

Sort sandboxes by their start time using the `order` parameter with `'asc'` or `'desc'`. The default is `'desc'` (newest first). Sorting applies to the complete result set before pagination.

```js JavaScript & TypeScript highlight={4} theme={"theme":"css-variables"}
import { Sandbox } from 'e2b'

const paginator = Sandbox.list({
  order: 'asc',
})

const sandboxes = await paginator.nextItems()
```

```python Python highlight={4} theme={"theme":"css-variables"}
from e2b import Sandbox

paginator = Sandbox.list(
    order="asc",
)

sandboxes = paginator.next_items()
```

### Advanced pagination

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

```js JavaScript & TypeScript highlight={4-5,16} theme={"theme":"css-variables"}
import { Sandbox } from 'e2b'

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

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

// Next page token
paginator.nextToken

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

```python Python  highlight={4-5,12} theme={"theme":"css-variables"}
from e2b import Sandbox

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

paginator.has_next  # Whether there is a next page
paginator.next_token  # Next page token

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

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:

```js JavaScript & TypeScript  highlight={7} theme={"theme":"css-variables"}
import { Sandbox, type SandboxInfo } from 'e2b'

const paginator = Sandbox.list()

// Loop through all pages
const sandboxes: SandboxInfo[] = []
while (paginator.hasNext) {
  const items = await paginator.nextItems()
  sandboxes.push(...items)
}
```

```python Python highlight={7} theme={"theme":"css-variables"}
from e2b import Sandbox, SandboxInfo, SandboxQuery

paginator = Sandbox.list()

# Loop through all pages
sandboxes: list[SandboxInfo] = []
while paginator.has_next:
    items = paginator.next_items()
    sandboxes.extend(items)
```

> [!WARNING]
>
> `GET /sandboxes` (without `/v2`) is deprecated. It returns every running sandbox in a single response, and returns `400 Bad Request` when more than 5,000 running sandboxes match your request. Use [`GET /v2/sandboxes`](https://docs.e2b.dev/api-reference/sandboxes/list-sandboxes-v2) or `Sandbox.list()` in the latest SDK, which page through results.
