Sandbox List

Use the Sandbox.list() method to list and query all running or paused sandbox instances. This method returns a paginator object that supports advanced query features such as filtering and pagination.

Basic Usage

List all sandboxes and retrieve the first page of results.

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  const paginator = await Sandbox.list()
  const items = await paginator.nextItems()

  console.log(`Found ${items.length} sandboxes`)
  items.forEach(sandbox => {
    console.log('Sandbox ID:', sandbox.sandboxId)
    console.log('Template ID:', sandbox.templateId)
    console.log('State:', sandbox.state)
    console.log('Started at:', sandbox.startedAt)
    console.log('Metadata:', sandbox.metadata)
  })
}

main()

Query Parameters

Filter by State

Use the query.state parameter to filter sandboxes by a specific state.

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  // List only running sandboxes
  const paginator = await Sandbox.list({
    query: { state: ['running'] }
  })
  const items = await paginator.nextItems()

  console.log(`${items.length} running sandboxes`)
}

main()

Filter by Metadata

Use the query.metadata parameter to filter sandboxes based on custom metadata.

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  // Filter by single metadata field
  const paginator = await Sandbox.list({
    query: { metadata: { userId: '123' } }
  })
  const items = await paginator.nextItems()

  console.log(`Found ${items.length} sandboxes for user 123`)
}

main()

Multiple Condition Filtering

When specifying multiple metadata fields, all must match (AND logic).

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  // Multiple metadata filters (AND logic)
  const paginator = await Sandbox.list({
    query: {
      metadata: {
        userId: '123',
        env: 'dev'
      }
    }
  })
  const items = await paginator.nextItems()
}

main()

Pagination Handling

Check for More Pages

Use the hasNext/has_next property to check if more data is available.

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  const paginator = await Sandbox.list()
  const firstPage = await paginator.nextItems()

  console.log(`First page: ${firstPage.length} items`)

  if (paginator.hasNext) {
    const secondPage = await paginator.nextItems()
    console.log(`Second page: ${secondPage.length} items`)
  }
}

main()

Iterate Through All Pages

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  const paginator = await Sandbox.list()
  const allSandboxes: any[] = []

  do {
    const items = await paginator.nextItems()
    allSandboxes.push(...items)
  } while (paginator.hasNext)

  console.log(`Total: ${allSandboxes.length} sandboxes`)
}

main()

Custom Page Size

Use the limit parameter to set the maximum number of items per page (default and maximum is 100).

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  const paginator = await Sandbox.list({ limit: 50 })
  const items = await paginator.nextItems()

  console.log(`Fetched ${items.length} items (max 50)`)
}

main()

Use Pagination Token

Use the nextToken/next_token to continue a previous query.

import { Sandbox } from '@e2b/code-interpreter'

async function main() {
  const paginator = await Sandbox.list({ limit: 10 })
  const firstPage = await paginator.nextItems()
  const token = paginator.nextToken

  console.log('Next token:', token)

  // Use token to get next page
  if (token) {
    const nextPaginator = await Sandbox.list({
      limit: 10,
      nextToken: token
    })
    const secondPage = await nextPaginator.nextItems()
  }
}

main()

SDK Version Differences

SDK Version	Return Type	Pagination Support
v1.x	Direct array	Not supported
v2.x+	Paginator object	Supported

This document is based on v2.x+ version.