Metrics

The E2B SDK's sandbox.getMetrics() and Sandbox.getMetrics(id) return CPU, memory, and disk samples for a sandbox, as on E2B. This page covers the two metrics endpoints, the fields of each sample, and how time ranges and buckets work.

PrerequisitesCopy Anchor Link

• The deployment is connected to an instance metrics store. See Instance metrics storage.

Without a store, both metrics endpoints return 501 with the capability name metrics.

Reading metricsCopy Anchor Link

The following example reads the samples of a sandbox and prints the CPU and memory use of the most recent one:

const samples = await sandbox.getMetrics();
const latest = samples.at(-1);
console.log(latest?.cpuUsedPct, latest?.memUsed);

The SDK calls one of two endpoints:

Sample fieldsCopy Anchor Link

Time range and bucketsCopy Anchor Link

SamplingCopy Anchor Link

• The node samples each running sandbox every 5 seconds.
• After a sandbox starts or resumes, samples begin with the second sampling, because the first one only establishes the CPU baseline.

Time rangeCopy Anchor Link

• Without start and end, the whole history of the sandbox within the retention period is returned.
• If only one end is given, the other end is the start or end of the sandbox's history.
• The end is no later than the current time, and the start is no earlier than the beginning of the retention period.
• start and end must be non-negative integers. If start is later than end, the request returns 400.
• Only buckets that have ended, at a time no later than the current time minus the query delay, are returned. Newer buckets are returned once their samples in the store are final, so samples from roughly the last 30 seconds are not returned yet. The deployment sets the query delay, 30 seconds by default; see E2B gateway configuration.

Bucket widthCopy Anchor Link

The bucket width depends on the query span, as in E2B:

• Each field of a bucket takes the maximum of the samples in that bucket, and the timestamp is the start of the bucket.
• Only buckets in which all seven fields have values are returned.
• The first and last buckets are both full buckets, so they may include samples just outside [start, end].

Pause, resume, and deletionCopy Anchor Link

• After a pause and resume, it is still the same series. Each resume starts a new Instance, and the gateway merges the samples of all Instances by sandbox.
• There are no samples while the sandbox is paused.
• After a sandbox is deleted, its metrics can still be queried within the retention period.

Missing sandboxes and empty resultsCopy Anchor Link

• A sandbox that does not exist, or that belongs to another deployment namespace, returns 404.
• A sandbox that exists but has no samples yet returns [].
• Unlike on E2B, a sandbox whose Platform's guest predates the sampling interface is not sampled by the node, and queries return [].

Batch endpointCopy Anchor Link

GET /sandboxes/metrics returns the latest sample of several sandboxes in one request:

• sandbox_ids is comma-separated, with at most 100 IDs and no duplicates. If it is missing or empty, the request returns 400.
• Each sandbox returns its latest sample up to "current time minus query delay".
• The latest sample is therefore usually 30 to 60 seconds old.
• A sandbox with no sample in the 30 seconds before that moment does not appear in the result. Neither do sandboxes that do not exist or belong to other deployments. The request still returns 200.

NotesCopy Anchor Link

• When the store is unreachable, the guest does not respond in time, or the node restarts, samples for that period are missing.
• When the store is unavailable, both endpoints return 500 with the message failed to fetch sandbox metrics.
• Each gateway instance caches the query result for a single sandbox for 1 second.
• Team metrics are not provided. See Not supported.

Next stepsCopy Anchor Link

• Instance metrics storage: connect a metrics store to the deployment.
• Sandboxes and lifecycle: pause, resume, and delete sandboxes.
• E2B compatibility: the other SDK areas the gateway supports.