Usage Aggregator
Usage
Usage Aggregator
GET
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
string
required
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).string
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.string
Exclusive upper bound. Same accepted formats as
from. Default:
now.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.string
-memoryGbSeconds (default) or -diskOverageGbSeconds.integer
Max items per page. Default 50, max 500.
string
Opaque cursor from a prior response’s
nextCursor.Response
string
required
RFC3339 echo of the effective window lower bound.
string
required
RFC3339 echo of the effective window upper bound.
string
required
Echo of the requested
groupBy value.object
required
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.object[]
required
Paginated rows, sorted by
sort (default: largest first).When groupBy=sandbox, each row is one sandbox:When groupBy=tag:<key>, each row is one tag value:object
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.string
Opaque cursor to pass as
cursor= on the next request, or null
when no further pages exist.