# List sandboxes (/docs/sandbox/list)

<!-- agent-signals: reading_time_min: 6 · est_tokens: 3520 · updated: 2026-07-30 -->
Related: [Auto-resume on request](/docs/sandbox/auto-resume.md), [Connect to running sandbox](/docs/sandbox/connect.md), [Environment variables](/docs/sandbox/environment-variables.md), [Filesystem-only snapshots](/docs/sandbox/filesystem-only-snapshots.md), [Sandbox forking](/docs/sandbox/fork.md), [Git integration](/docs/sandbox/git-integration.md)

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>

### Listing sandboxes [#listing-sandboxes]

The `Sandbox.list()` method 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>
  <CodeBlockTabs defaultValue="JavaScript & TypeScript" groupId="javascript-typescript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="JavaScript & TypeScript">
        JavaScript & TypeScript
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="JavaScript & TypeScript">
      ```js highlight={6,11,14,24}  
      import { Sandbox, SandboxInfo } 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
      const nextPage = await paginator.nextItems()
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Python">
      ```python highlight={5,9,12,22}  
      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
      nextPage = paginator.next_items()
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

The code above will output something like this:

<CodeGroup>
  <CodeBlockTabs defaultValue="JavaScript & TypeScript" groupId="javascript-typescript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="JavaScript & TypeScript">
        JavaScript & TypeScript
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="JavaScript & TypeScript">
      ```bash  
      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
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Python">
      ```bash  
      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
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

### Filtering sandboxes [#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>
  <CodeBlockTabs defaultValue="JavaScript & TypeScript" groupId="javascript-typescript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="JavaScript & TypeScript">
        JavaScript & TypeScript
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="JavaScript & TypeScript">
      ```js highlight={9,13}  
      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()
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Python">
      ```python highlight={9,14}  
      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()
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

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

<CodeGroup>
  <CodeBlockTabs defaultValue="JavaScript & TypeScript" groupId="javascript-typescript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="JavaScript & TypeScript">
        JavaScript & TypeScript
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="JavaScript & TypeScript">
      ```js highlight={6-8,15,18}  
      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()
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Python">
      ```python highlight={6-8,16-17}  
      from e2b import Sandbox, SandboxQuery, SandboxState

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

      # List running sandboxes that has `userId` key with value `123` and `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()
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

### Advanced pagination [#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.

<CodeGroup>
  <CodeBlockTabs defaultValue="JavaScript & TypeScript" groupId="javascript-typescript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="JavaScript & TypeScript">
        JavaScript & TypeScript
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="JavaScript & TypeScript">
      ```js highlight={4-5,16}  
      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()
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Python">
      ```python highlight={5-6,13}  
      from e2b import Sandbox

      # List running sandboxes that has `userId` key with value `123` and `env` key with value `dev`.
      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()
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</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>
  <CodeBlockTabs defaultValue="JavaScript & TypeScript" groupId="javascript-typescript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="JavaScript & TypeScript">
        JavaScript & TypeScript
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="JavaScript & TypeScript">
      ```js highlight={7}  
      import { Sandbox } from 'e2b'

      const paginator = Sandbox.list()

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

    <CodeBlockTab value="Python">
      ```python highlight={7}  
      from e2b import Sandbox, SandboxQuery

      paginator = Sandbox.list()

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

## Old SDK (v1.x.y) [#old-sdk-v1xy]

<Note>
  If you're using SDK with version lower than `2.0.0`, the `Sandbox.list()` method behaves differently.
</Note>

<CodeGroup>
  <CodeBlockTabs defaultValue="JavaScript & TypeScript" groupId="javascript-typescript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="JavaScript & TypeScript">
        JavaScript & TypeScript
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="JavaScript & TypeScript">
      ```js highlight={11}  
      import { Sandbox } from 'e2b'

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

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

    <CodeBlockTab value="Python">
      ```python highlight={11}  
      from e2b import Sandbox

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

      # List all running sandboxes.
      running_sandboxes = Sandbox.list() 
      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)
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

## Filtering sandboxes [#filtering-sandboxes-1]

You can filter sandboxes by specifying [Metadata](/docs/sandbox/metadata) 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>
  <CodeBlockTabs defaultValue="JavaScript & TypeScript" groupId="javascript-typescript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="JavaScript & TypeScript">
        JavaScript & TypeScript
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="JavaScript & TypeScript">
      ```js highlight={6-8,15}  
      import { Sandbox } from 'e2b'

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

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

    <CodeBlockTab value="Python">
      ```python highlight={7-9,17-18}  
      from e2b import Sandbox
      from e2b.sandbox.sandbox_api import SandboxQuery

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

      # 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",
                  "env": "dev",
              }
          ),
      )
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>