Metrics and usage

All of these need machines:read. Sandbox.usage also works with images:read.

// the last 15 minutes of CPU and memory
const samples = await sbx.getMetrics({
  since: new Date(Date.now() - 15 * 60_000),
})
// what it used since the start of October (UTC)
const usage = await Sandbox.getUsage(sbx.sandboxId, {
  from: new Date('2026-10-01T00:00:00Z'),
})
console.log(usage.runningSeconds, usage.vcpuSeconds)

getMetrics

Get a machine’s resource samples: one per 30 s, oldest first, measured on the host.

sbx.getMetrics(opts?: SandboxMetricsOpts): Promise<SandboxMetrics[]>
Sandbox.getMetrics(sandboxId: string, opts?: SandboxMetricsOpts & ConnectionOptions): Promise<SandboxMetrics[]>

since (a Date) is the start of the window: by default 5 minutes ago, at most 24 h back.

There are samples only for the times in the window when the machine ran. A machine that is paused or stopped now still returns the samples from when it ran. A machine that did not run in the window gets an empty list.
The last sample of a running machine is its host’s latest report (at most about 30 s old, CPU and memory only), so a new machine shows its first sample within about 30 s.
The CLI prints the same: instabox metrics <id-or-name> [--json].

Field	Type	What
`timestamp`	`Date`	When the sample was taken
`cpuUsedPct`	`number`	CPU time over the machine’s vCPUs, 0 to 100
`cpuCount`	`number`	vCPUs
`memUsed`	`number`	Guest memory touched, in bytes
`memTotal`	`number`	Memory size, in bytes
`diskTotal`	`number`	Disk (`/data`) size, in bytes
`diskUsed`	`number`	Only on the latest sample of a running machine: bytes used on `/data`, read inside the machine (refreshed in the background at most once a minute, at most 10 minutes old)

For /data and / with a fullness level, use GET /v1/machines/{id}/disk or instabox disk <id-or-name> (CLI reference).

getUsage

Get what a machine used between from and to (both Dates), for billing your own customers.

sbx.getUsage(opts?: SandboxUsageOpts): Promise<SandboxUsage>
Sandbox.getUsage(sandboxId: string, opts?: SandboxUsageOpts & ConnectionOptions): Promise<SandboxUsage>

The default range is the current UTC month: from is the start of the month, and to is now. to is at most 366 days after from. A deleted machine’s usage stays readable by its account, by ID. Running time is recorded from the deploy of 2026-10-14. Earlier time is not counted.

Field	Type	What
`from`, `to`	`Date`	The window
`runningSeconds`	`number`	Seconds running, not paused or stopped
`vcpuSeconds`	`number`	vCPUs times running seconds
`memGiBSeconds`	`number`	Memory GiB times running seconds
`diskGiBSeconds`	`number`	Disk (`/data`) size times the seconds it existed in the window, paused or stopped included
`egressBytes`	`number`	Bytes sent to the public internet, by whole hour (every hour from the one `from` falls in up to `to`), billed or not. Absent from older servers

Sandbox.usage

Get your counts, stored bytes and limits (GET /v1/usage).

Sandbox.usage(opts?: ConnectionOptions): Promise<Usage>

Bytes are measured about hourly.

interface Usage {
  computedAt: string | null // when bytes were measured
  logicalBytes: number
  storedBytes: number
  exclusiveBytes: number // deprecated: always 0
  machines: number
  snapshots: number
  limits: UsageLimits // maxMachines, maxSnapshots, maxStoredGiB,
                      // machineSpec?, liveSnapshots?, vault?
  storage?: UsageStorage // storedBytes by machine
}

storage has machines (each with id, name, state, sizeBytes, diskBytes, snapshots and snapshotBytes), deletedMachineSnapshots and deletedMachineSnapshotBytes. computedAt is null and storage absent before your first measurement.

Get started

TypeScript

Python

Metrics and usage

getMetrics

getUsage

Sandbox.usage

​getMetrics

​getUsage

​Sandbox.usage

getMetrics

getUsage

Sandbox.usage