Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.opencomputer.dev/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
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

GET /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

{
  "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, 230 bytes/GiB), so used / allocated gives a clean utilization fraction.

​
Calling it

import { 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.