Usage Monitoring

​

Example

​

Request

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

​

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 }
  ]
}

​

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.

​

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
}

curl -s "$OPENCOMPUTER_API_URL/api/sandboxes/sb-abc/usage?from=2026-05-27T00:00:00Z&to=2026-05-27T01:00:00Z" \
  -H "X-API-Key: $OPENCOMPUTER_API_KEY" | jq '.totals'

​

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.