Skip to main content
GET
/
api
/
sandboxes
/
{id}
/
usage
Sandbox Usage
curl --request GET \
  --url https://app.opencomputer.dev/api/sandboxes/{id}/usage \
  --header 'X-API-Key: <api-key>'
{
  "sandboxId": "sb-abc",
  "alias": "my-agent",
  "from":   "2026-05-27T00:00:00Z",
  "to":     "2026-05-28T00:00:00Z",
  "totals": {
    "memoryAllocatedGbSeconds":  86400,
    "memoryUsedGbSeconds":       51640,
    "uptimeSeconds":             86400,
    "memoryAllocatedPeakMb":      1024,
    "memoryUsedPeakMb":            742
  },
  "points": [
    {
      "ts":                       "2026-05-27T00:00:00Z",
      "memoryAllocatedGbSeconds":      60.0,
      "memoryUsedGbSeconds":           35.86,
      "uptimeSeconds":                 60,
      "allocatedMemoryMb":           1024,
      "usedMemoryMbAvg":              612,
      "usedMemoryMbPeak":             720
    },
    {
      "ts":                       "2026-05-27T00:01:00Z",
      "memoryAllocatedGbSeconds":      60.0,
      "memoryUsedGbSeconds":           40.02,
      "uptimeSeconds":                 60,
      "allocatedMemoryMb":           1024,
      "usedMemoryMbAvg":              683,
      "usedMemoryMbPeak":             742
    }
  ]
}
Per-sandbox memory usage over a window, as 1-minute points plus envelope totals. Allocated memory is the tier the sandbox was provisioned at, integrated over time; used memory is the actual resident memory consumed by the sandbox process, sampled every 60s.
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.

Request

id
string
required
Sandbox ID.
from
string
Lower bound. Accepts either an ISO date (2026-05-27, interpreted as UTC midnight) or an RFC3339 timestamp. Default: now minus 1 hour.
to
string
Upper bound. Same accepted formats as from. Default: now. Window must be ≤ 30 days.

Response

sandboxId
string
required
Echo of the requested sandbox ID.
alias
string
The sandbox’s display name (set at create time). Absent if no alias was provided.
from
string
required
RFC3339 lower bound of the window the response covers — either the caller’s from, or the server default (now - 1h) when omitted.
to
string
required
RFC3339 upper bound. Either the caller’s to, or the server default (now) when omitted.
totals
object
required
Envelope totals for the full window. Each additive field equals the sum of the matching field across points[] — useful for getting the headline numbers without iterating.
points
object[]
required
Time-ordered array of 1-minute buckets covering [from, to). Buckets are minute-aligned in UTC. Boundary buckets are clamped to the original window — a mid-minute from produces a partial first bucket whose integrals reflect only the overlap with the requested range.Minutes where the sandbox was not provisioned (before first start, after final stop) appear with all fields at 0 rather than as missing entries — gaps read as continuous flat zero on a chart.

Units

All *GbSeconds fields are GiB-seconds (binary, 230 bytes/GiB), not decimal GB. For a sandbox provisioned at 1024 MiB running for one minute, memoryAllocatedGbSeconds is 1024/1024 × 60 = 60. For a measured RSS of 612 MiB, memoryUsedGbSeconds is 612/1024 × 60 ≈ 35.86.
{
  "sandboxId": "sb-abc",
  "alias": "my-agent",
  "from":   "2026-05-27T00:00:00Z",
  "to":     "2026-05-28T00:00:00Z",
  "totals": {
    "memoryAllocatedGbSeconds":  86400,
    "memoryUsedGbSeconds":       51640,
    "uptimeSeconds":             86400,
    "memoryAllocatedPeakMb":      1024,
    "memoryUsedPeakMb":            742
  },
  "points": [
    {
      "ts":                       "2026-05-27T00:00:00Z",
      "memoryAllocatedGbSeconds":      60.0,
      "memoryUsedGbSeconds":           35.86,
      "uptimeSeconds":                 60,
      "allocatedMemoryMb":           1024,
      "usedMemoryMbAvg":              612,
      "usedMemoryMbPeak":             720
    },
    {
      "ts":                       "2026-05-27T00:01:00Z",
      "memoryAllocatedGbSeconds":      60.0,
      "memoryUsedGbSeconds":           40.02,
      "uptimeSeconds":                 60,
      "allocatedMemoryMb":           1024,
      "usedMemoryMbAvg":              683,
      "usedMemoryMbPeak":             742
    }
  ]
}

Use the aggregator for cross-sandbox questions

To rank sandboxes by usage, use GET /api/usage — that endpoint serves cross-sandbox aggregates and supports filter/sort/cursor. The per-sandbox endpoint here is for “look at this one sandbox in detail.”