Usage Monitoring

GET /api/sandboxes/:id/usage returns a per-minute time series of a sandbox's memory — both the tier you provisioned and what the process actually consumed — together with envelope totals. Use it to answer "am I over-paying for this sandbox" or "when did memory spike?" For cross-sandbox leaderboards (rank by usage, group by tag) see the aggregator at GET /api/usage instead.

Preview: Usage and tag APIs are new. Endpoints, response fields, and SDK method names may change before GA; temporary inaccuracies or rough edges are possible while the surface settles.

Ask AI about this page

Example

Allocated tier as a step line (it changes only on resize), measured usage as a smooth curve. The gap between them is paid-for headroom.

Everything on the chart — the resize step, the peak, the brief gap — falls out of points[] directly: allocatedMemoryMb is the step, usedMemoryMbPeak finds the peak, uptimeSeconds: 0 marks downtime.

Request

http

1GET /api/sandboxes/sb-abc/usage?from=2026-05-27T00:00:00Z&to=2026-05-27T01:00:00Z

Path carries the sandbox ID. from and to are optional and accept ISO dates (YYYY-MM-DD, interpreted as UTC midnight) or RFC3339 timestamps; omit them for the last hour. Max window is 30 days. Full param reference: the API page.

Response

json

1234567891011121314151617{
  "sandboxId": "sb-abc",
  "alias": "my-agent",
  "from": "2026-05-27T00:00:00Z",
  "to":   "2026-05-27T01:00:00Z",
  "totals": {
    "memoryAllocatedGbSeconds": 3600,
    "memoryUsedGbSeconds":      2180,
    "uptimeSeconds":            3600,
    "memoryAllocatedPeakMb":    1024,
    "memoryUsedPeakMb":          742
  },
  "points": [
    { "ts": "2026-05-27T00:00:00Z", "memoryAllocatedGbSeconds": 60, "memoryUsedGbSeconds": 35.86, "uptimeSeconds": 60, "allocatedMemoryMb": 1024, "usedMemoryMbAvg": 612, "usedMemoryMbPeak": 720 },
    { "ts": "2026-05-27T00:01:00Z", "memoryAllocatedGbSeconds": 60, "memoryUsedGbSeconds": 40.02, "uptimeSeconds": 60, "allocatedMemoryMb": 1024, "usedMemoryMbAvg": 683, "usedMemoryMbPeak": 742 }
  ]
}

totals is the server-side sum of points[] — summing any additive field across the array reproduces the matching totals.* exactly. Full field semantics live in the API reference.

Allocated vs used

memoryAllocatedGbSeconds — the tier you provisioned, integrated over time. Same physical quantity the bill is computed from. Resize mid-window shows up as a time-weighted blend in the affected bucket.
memoryUsedGbSeconds — measured resident memory, sampled every 60s and integrated. The headroom signal: low ratio of used over allocated means you're over-provisioned.

Both are in GiB-seconds (binary, 2³⁰ bytes/GiB), so used / allocated gives a clean utilization fraction.

Calling it

typescript

123456789101112131415import { Usage } from "@opencomputer/sdk";

const usage = new Usage(
  "https://app.opencomputer.dev",
  process.env.OPENCOMPUTER_API_KEY!,
);

// Default window = last 1 hour. Pass `from`/`to` for up to 30 days.
const r = await usage.forSandbox("sb-abc");
const pct = 100 * r.totals.memoryUsedGbSeconds / r.totals.memoryAllocatedGbSeconds;
console.log(`${pct.toFixed(0)}% utilization`);

for (const p of r.points) {
  // p.ts, p.usedMemoryMbAvg, p.allocatedMemoryMb — ready to chart
}

Full TypeScript SDK reference: Usage & Tags.

Bucket semantics

Buckets are 1 minute, UTC-aligned; boundary buckets clamp to the original window so a mid-minute from doesn't over-report.
Minutes where the sandbox isn't running emit zero-points — gaps read as continuous flat zero on a chart, not nulls.
If a measurement is missed, uptimeSeconds still reads 60 (the sandbox was running) but usedMemoryMbAvg reads 0 — visible as a brief dip under an otherwise continuous allocated line.
The first non-zero usedMemoryMbAvg for a freshly-created sandbox appears a few minutes in. Workloads that finish faster than that may not register any measured usage even though they ran.
Window max is 30 days.