Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Usage Aggregator

Aggregate usage grouped by sandbox or by tag. Dollars are not exposed — the platform returns the same physical quantities the invoice is computed from. For per-sandbox time-series drilldown (memory utilization over time, 1-minute resolution), see GET /api/sandboxes/:id/usage.
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.
All *GbSeconds fields are GiB-seconds (binary, 230 bytes/GiB), not decimal GB. For a sandbox provisioned at 1024 MiB running for one second, memoryGbSeconds is 1.
Freshness: accurate to the minute under normal conditions. A sandbox that exited uncleanly continues to accrue against its provisioned tier until the platform reconciles state — the same behavior the billing pipeline uses, so the numbers here match the invoice.

Request

query groupBystringrequired
sandbox for top sandboxes, or tag:<key> for usage by tag value. Keys may contain : — everything after the first : is the tag key (so groupBy=tag:team:payments groups by the key team:payments).
query fromstring
Inclusive lower bound. Accepts either an ISO date (2026-05-27, interpreted as UTC midnight) or an RFC3339 timestamp. Default: now minus 30 days. Max window: 90 days.
query tostring
Exclusive upper bound. Same accepted formats as from. Default: now.
query filter[tag:<key>]string
One param per dimension. Comma-separated values are OR'd within that dimension; different filter[...] params are AND'd across dimensions. Passing the same filter[...] key twice returns 400 — put multiple OR values in one comma-separated string instead. Empty value (filter[tag:team]=) matches sandboxes without the team key.
query sortstring
-memoryGbSeconds (default) or -diskOverageGbSeconds.
query limitinteger
Max items per page. Default 50, max 500.
query cursorstring
Opaque cursor from a prior response's nextCursor.

Response

fromstringrequired
RFC3339 echo of the effective window lower bound.
tostringrequired
RFC3339 echo of the effective window upper bound.
groupBystringrequired
Echo of the requested groupBy value.
totalobjectrequired
Aggregate across all rows matching the window and filters, not just the current page. Use this for headline numbers; sum items[] if you need a per-page subtotal instead.
properties
memoryGbSecondsnumberrequired
Total provisioned memory × time across matching sandboxes, in GiB-seconds.
diskOverageGbSecondsnumberrequired
Total disk-overage × time. Disk usage within the free allowance does not contribute; this is the billable excess.
itemsobject[]required
Paginated rows, sorted by sort (default: largest first).
When groupBy=sandbox, each row is one sandbox:
groupBy=sandbox row
sandboxIdstringrequired
The sandbox identifier.
aliasstring
Display name set at create time. Absent when none was provided.
statusstring
Current sandbox status (e.g., running, hibernated, stopped). Absent when no session exists.
tagsobjectrequired
Current tag set on the sandbox. Empty object when none.
tagsLastUpdatedAtstring
RFC3339 timestamp of the most recent tag change, or null if no tags exist.
memoryGbSecondsnumberrequired
Provisioned memory × time for this sandbox in the window.
diskOverageGbSecondsnumberrequired
Disk overage × time for this sandbox.
When groupBy=tag:<key>, each row is one tag value:
groupBy=tag row
tagKeystringrequired
The tag key from the request (e.g., team).
tagValuestringrequired
The tag value for this group.
memoryGbSecondsnumberrequired
Total provisioned memory × time across sandboxes carrying tagKey=tagValue.
diskOverageGbSecondsnumberrequired
Total disk overage × time for the same group.
sandboxCountintegerrequired
Distinct sandboxes contributing to this row.
untaggedobject
Only present when groupBy=tag:<key>. Sibling bucket for sandboxes that lack the grouping key — without it, untagged sandboxes would silently disappear from the rollup. Same shape as a tag row minus tagKey/tagValue.
properties
memoryGbSecondsnumberrequired
Total provisioned memory × time across untagged sandboxes.
diskOverageGbSecondsnumberrequired
Total disk overage × time.
sandboxCountintegerrequired
Distinct sandboxes in the untagged bucket.
nextCursorstring
Opaque cursor to pass as cursor= on the next request, or null when no further pages exist.
Response example
{
  "from": "2026-03-23T00:00:00Z",
  "to":   "2026-04-22T00:00:00Z",
  "groupBy": "sandbox",
  "total": { "memoryGbSeconds": 20000, "diskOverageGbSeconds": 360 },
  "items": [
    {
      "sandboxId": "sb-abc",
      "alias": "my-agent",
      "status": "running",
      "tags": { "env": "prod", "team": "payments" },
      "tagsLastUpdatedAt": "2026-04-19T14:02:00Z",
      "memoryGbSeconds": 8000,
      "diskOverageGbSeconds": 120
    }
  ],
  "nextCursor": null
}