# Sandbox metadata (/docs/sandbox/metadata)

<!-- agent-signals: reading_time_min: 1 · est_tokens: 529 · 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)

Metadata is a way to attach arbitrary key-value pairs for a sandbox.

This is useful in various scenarios, for example:

* Associate a sandbox with a user session.
* Store custom user data for a sandbox like API keys.
* Associate a sandbox with a user ID and [connect to it later](/docs/sandbox/connect).

You specify metadata when creating a sandbox and can access it later through listing running sandboxes with `Sandbox.list()` 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}  
      import { Sandbox } from 'e2b'

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

      // List running sandboxes and access metadata.
      const paginator = await Sandbox.list()
      const runningSandboxes = await paginator.nextItems()
      // Will print:
      // {
      //   'userId': '123',
      // }
      console.log(runningSandboxes[0].metadata)
      ```
    </CodeBlockTab>

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

      # Create sandbox with metadata.
      sandbox = Sandbox.create(
        metadata={
          'userId': '123',
        },
      )

      # List running sandboxes and access metadata.
      paginator = Sandbox.list()
      running_sandboxes = paginator.next_items()
      # Will print:
      # {
      #   'userId': '123',
      # }
      print(running_sandboxes[0].metadata)
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

## Filtering sandboxes by metadata [#filtering-sandboxes-by-metadata]

You can also filter sandboxes by metadata, you can find more about it [here](/docs/sandbox/list#filtering-sandboxes).