> ## 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.
# Usage Monitoring
> Inspect a sandbox's memory allocation and actual utilization over time
[`GET /api/sandboxes/:id/usage`](/api-reference/usage/get-sandbox-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`](/api-reference/usage/get-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
```http theme={null}
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](/api-reference/usage/get-sandbox-usage).
## Response
```json theme={null}
{
"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](/api-reference/usage/get-sandbox-usage).
## 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
```typescript TypeScript theme={null}
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
}
```
```bash cURL theme={null}
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'
```
Full TypeScript SDK reference: [Usage & Tags](/reference/typescript-sdk/usage).
## 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**.