Documentation

E2B provides several ways to monitor and track your sandboxes: resource metrics via the SDK and CLI, a REST API for lifecycle event history, and webhooks for real-time notifications.

Metrics

Sandbox metrics let you monitor CPU, memory, and disk usage of running sandboxes. Metrics are collected every 5 seconds.

Getting metrics using the SDKs

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

const sbx = await Sandbox.create()
console.log('Sandbox created', sbx.sandboxId)

// Wait for a few seconds to collect some metrics
await new Promise((resolve) => setTimeout(resolve, 10_000))

const metrics = await sbx.getMetrics()

// You can also get the metrics by sandbox ID:
// const metrics = await Sandbox.getMetrics(sbx.sandboxId)

console.log('Sandbox metrics:', metrics)

// Sandbox metrics:
// [
//   {
//     timestamp: 2025-07-28T08:04:05.000Z,
//     cpuUsedPct: 20.33,
//     cpuCount: 2,
//     memUsed: 32681984,  // in bytes
//     memTotal: 507592704,  // in bytes
//     diskUsed: 1514856448,  // in bytes
//     diskTotal: 2573185024  // in bytes
//   },
//   {
//     timestamp: 2025-07-28T08:04:10.000Z,
//     cpuUsedPct: 0.2,
//     cpuCount: 2,
//     memUsed: 33316864,  // in bytes
//     memTotal: 507592704, // in bytes
//     diskUsed: 1514856448,  // in bytes
//     diskTotal: 2573185024  // in bytes
//   }
// ]

Getting metrics using the CLI

e2b sandbox metrics <sandbox_id>

# Metrics for sandbox <sandbox_id>
#
# [2025-07-25 14:05:55Z]  CPU:  8.27% /  2 Cores | Memory:    31 / 484   MiB | Disk:  1445 / 2453  MiB
# [2025-07-25 14:06:00Z]  CPU:   0.5% /  2 Cores | Memory:    32 / 484   MiB | Disk:  1445 / 2453  MiB
# [2025-07-25 14:06:05Z]  CPU:   0.1% /  2 Cores | Memory:    32 / 484   MiB | Disk:  1445 / 2453  MiB
# [2025-07-25 14:06:10Z]  CPU:   0.3% /  2 Cores | Memory:    32 / 484   MiB | Disk:  1445 / 2453  MiB

It may take a second or more to get the first metrics after the sandbox is created. Until the first metrics are collected from the sandbox, you will get an empty array.

Lifecycle events API

The lifecycle API provides RESTful endpoints to request the latest sandbox lifecycle events. This allows you to track when sandboxes are created, paused, resumed, updated, snapshotted, or killed, along with metadata. All requests require authentication using your team API key. Query Parameters:

offset (optional): Number of events to skip (default: 0, min: 0)
limit (optional): Number of events to return (default: 10, min: 1, max: 100)
orderAsc (optional): Sort order - true for ascending, false for descending (default: false)

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

const sbx = await Sandbox.create()

// Get the latest events for a specific sandbox
const resp1 = await fetch(
  `https://api.e2b.app/events/sandboxes/${sbx.id}`,
  {
    method: 'GET',
    headers: {
      'X-API-Key': E2B_API_KEY,
    },
  }
)
const sandboxEvents = await resp1.json()

// Get the latest 10 events for all sandboxes associated with the team
const resp2 = await fetch(
  'https://api.e2b.app/events/sandboxes?limit=10',
  {
    method: 'GET',
    headers: {
      'X-API-Key': E2B_API_KEY,
    },
  }
)
const teamSandboxEvents = await resp2.json()

console.log(teamSandboxEvents)

// [
//   {
//     "version": "v1",
//     "id": "f5911677-cb60-498f-afed-f68143b3cc59",
//     "type": "sandbox.lifecycle.killed",
//     "eventData": null,
//     "sandboxBuildId": "a979a14b-bdcc-49e6-bc04-1189fc9fe7c2",
//     "sandboxExecutionId": "1dae9e1c-9957-4ce7-a236-a99d5779aadf",
//     "sandboxId": "${SANDBOX_ID}",
//     "sandboxTeamId": "460355b3-4f64-48f9-9a16-4442817f79f5",
//     "sandboxTemplateId": "rki5dems9wqfm4r03t7g",
//     "timestamp": "2025-08-06T20:59:36Z"
//   },
//   {
//     "version": "v1",
//     "id": "30b09e11-9ba2-42db-9cf6-d21f0f43a234",
//     "type": "sandbox.lifecycle.updated",
//     "eventData": {
//       "set_timeout": "2025-08-06T20:59:59Z"
//     },
//     "sandboxBuildId": "a979a14b-bdcc-49e6-bc04-1189fc9fe7c2",
//     "sandboxExecutionId": "1dae9e1c-9957-4ce7-a236-a99d5779aadf",
//     "sandboxId": "${SANDBOX_ID}",
//     "sandboxTeamId": "460355b3-4f64-48f9-9a16-4442817f79f5",
//     "sandboxTemplateId": "rki5dems9wqfm4r03t7g",
//     "timestamp": "2025-08-06T20:59:29Z"
//   },
//   [...]
//   {
//     "version": "v1",
//     "id": "0568572b-a2ac-4e5f-85fa-fae90905f556",
//     "type": "sandbox.lifecycle.created",
//     "eventData": null,
//     "sandboxBuildId": "a979a14b-bdcc-49e6-bc04-1189fc9fe7c2",
//     "sandboxExecutionId": "1dae9e1c-9957-4ce7-a236-a99d5779aadf",
//     "sandboxId": "${SANDBOX_ID}",
//     "sandboxTeamId": "460355b3-4f64-48f9-9a16-4442817f79f5",
//     "sandboxTemplateId": "rki5dems9wqfm4r03t7g",
//     "timestamp": "2025-08-06T20:59:24Z"
//   }
// ]

Lifecycle webhooks

Webhooks provide a way for notifications to be delivered to an external web server whenever certain sandbox lifecycle events occur. This allows you to receive real-time updates about sandbox creation, updates, and termination without having to poll the API. All webhook requests require authentication using your team API key.

Register webhook

Register a new webhook to receive sandbox lifecycle events. The webhook will be registered for the team ID associated with your API key. All events specified during webhook creation will be sent to URL provided during registration with the webhook payload.

// Register a new webhook
const resp = await fetch(
  'https://api.e2b.app/events/webhooks',
  {
    method: 'POST',
    headers: {
      'X-API-Key': E2B_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'My Sandbox Webhook',
      url: 'https://your-webhook-endpoint.com/webhook',
      enabled: true,
      events: ['sandbox.lifecycle.created', 'sandbox.lifecycle.updated', 'sandbox.lifecycle.killed'],
      signatureSecret: 'secret-for-event-signature-verification'
    }),
  }
)

if (resp.status === 201) {
  console.log('Webhook registered successfully')
}

List webhooks

List all registered webhooks for your team.

// List webhooks
const resp = await fetch(
  'https://api.e2b.app/events/webhooks',
  {
    method: 'GET',
    headers: {
      'X-API-Key': E2B_API_KEY
    },
  },
)

if (resp.status === 200) {
  console.log('Webhooks listed successfully')
  console.log(await resp.json())
}

Get webhook configuration

Retrieve the current webhook configuration for your team.

// Get webhook configuration
const resp = await fetch(
  `https://api.e2b.app/events/webhooks/${webhookID}`,
  {
    method: 'GET',
    headers: {
      'X-API-Key': E2B_API_KEY,
    },
  }
)
const webhookConfig = await resp.json()
console.log(webhookConfig)
// {
//   "id": "<webhook-id>",
//   "teamID": "<your-team-id>",
//   "name": "My Sandbox Webhook",
//   "createdAt": "2025-08-06T21:00:00Z",
//   "enabled": true,
//   "url": "https://your-webhook-endpoint.com/webhook",
//   "events": ["sandbox.lifecycle.created", "sandbox.lifecycle.killed"]
// }

Update webhook configuration

Update an existing webhook configuration. The update will replace the previous configuration fields with provided fields.

// Update webhook configuration
const resp = await fetch(
  `https://api.e2b.app/events/webhooks/${webhookID}`,
  {
    method: 'PATCH',
    headers: {
      'X-API-Key': E2B_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      url: 'https://your-updated-webhook-endpoint.com/webhook',
      enabled: false,
      events: ['sandbox.lifecycle.created']
    }),
  }
)

if (resp.status === 200) {
  console.log('Webhook updated successfully')
}

Delete webhook

Unregister the webhook.

// Delete webhook configuration
const resp = await fetch(
  `https://api.e2b.app/events/webhooks/${webhookID}`,
  {
    method: 'DELETE',
    headers: {
      'X-API-Key': E2B_API_KEY,
    },
  }
)

if (resp.status === 200) {
  console.log('Webhook deleted successfully')
}

Webhook payload

When a webhook is triggered, your endpoint will receive a POST request with a JSON payload containing the sandbox event data. The payload structure matches the event format from the API:

{
  "version": "v2",
  "id": "<event-id>",
  "type": "<sandbox-event-type>",
  "eventData": {
    "sandbox_metadata": {
      "<custom-key>": "<custom-value>"
    },
    "execution": {
      "started_at": "2025-08-06T20:58:24Z",
      "vcpu_count": 2,
      "memory_mb": 512,
      "execution_time": 1000,
    }
  },
  "sandboxBuildId": "<template-build-id>",
  "sandboxExecutionId": "<sandbox-unique-execution-id>",
  "sandboxId": "<your-sandbox-id>",
  "sandboxTeamId": "<your-team-id>",
  "sandboxTemplateId": "<your-template-id>",
  "timestamp": "2025-08-06T20:59:24Z"
}

eventData.execution contains sandbox execution details and is included on sandbox.lifecycle.killed and sandbox.lifecycle.paused events:

started_at - UTC RFC3339 timestamp when the current sandbox execution started
vcpu_count - Number of vCPUs assigned to the sandbox
memory_mb - Memory assigned to the sandbox in MB
execution_time - Sandbox runtime in milliseconds

Webhook verification

To ensure the authenticity of webhook requests, each request includes a signature in the e2b-signature header. You can verify the signature using the signature secret you provided when registering the webhook. This confirms that the request originated from E2B and has not been tampered with.

function verifyWebhookSignature(secret : string, payload : string, payloadSignature : string) {
    const expectedSignatureRaw = crypto.createHash('sha256').update(secret + payload).digest('base64');
    const expectedSignature = expectedSignatureRaw.replace(/=+$/, '');
    return  expectedSignature == payloadSignature
}

const payloadValid = verifyWebhookSignature(secret, webhookBodyRaw, webhookSignatureHeader)
if (payloadValid) {
    console.log("Payload signature is valid")
} else {
    console.log("Payload signature is INVALID")
}

Webhook request headers

When a webhook is sent, E2B adds headers to help you verify authenticity and debug delivery:

e2b-webhook-id - Webhook ID that triggered the event
e2b-delivery-id - Unique ID for the delivery attempt
e2b-signature-version - Currently always v1, reserved for future use
e2b-signature - Signature for verifying the request authenticity

Available event types

The following event types can be subscribed to via webhooks, they are used as the type field in the payload.

sandbox.lifecycle.created - Sandbox creation
sandbox.lifecycle.killed - Sandbox termination
sandbox.lifecycle.updated - Sandbox configuration updates
sandbox.lifecycle.paused - Sandbox pausing
sandbox.lifecycle.resumed - Sandbox resuming
sandbox.lifecycle.checkpointed - Sandbox snapshot created

Getting started

Use cases

Agents in sandbox

Sandbox

Templates

Filesystem

Commands

MCP gateway

Code interpreting

CLI

Deployment

Migration

Troubleshooting

Observability

Metrics

Getting metrics using the SDKs

Getting metrics using the CLI

Lifecycle events API

Lifecycle webhooks

Register webhook

List webhooks

Get webhook configuration

Update webhook configuration

Delete webhook

Webhook payload

Webhook verification

Webhook request headers

Available event types

Getting started

Use cases

Agents in sandbox

Sandbox

Templates

Filesystem

Commands

MCP gateway

Code interpreting

CLI

Deployment

Migration

Troubleshooting

​Metrics

​Getting metrics using the SDKs

​Getting metrics using the CLI

​Lifecycle events API

​Lifecycle webhooks

​Register webhook

​List webhooks

​Get webhook configuration

​Update webhook configuration

​Delete webhook

​Webhook payload

​Webhook verification

​Webhook request headers

​Available event types

Metrics

Getting metrics using the SDKs

Getting metrics using the CLI

Lifecycle events API

Lifecycle webhooks

Register webhook

List webhooks

Get webhook configuration

Update webhook configuration

Delete webhook

Webhook payload

Webhook verification

Webhook request headers

Available event types