Read usage
What this account has used — running hours weighted by cores and memory, and the storage it holds — with the per-computer breakdown behind the totals. The same figures the dashboard shows, and the read to build a spend check around: a loop that launches computers is the caller that can run up a bill without noticing.
The default window is the period your plan bills on, which is what makes this comparable with an invoice — up to the 62 days this endpoint reads at once. A period longer than that (an annual plan, a long trial) is reported in period in full and MEASURED over the most recent 62 days of it; from and to in the response always say which window the figures cover, so compare those against period before reconciling. from and to override the default, and you will want them for a window that has closed — the billing period is the CURRENT one, and by the time an invoice arrives the period it covers is not.
READ degraded AND unmetered BEFORE USING THE NUMBERS. Every figure here is a sum across the hypervisors your computers are on, so a host that did not contribute does not leave a hole you could notice — it leaves a total that is quietly too small. Those two flags are how that says so, and it is why this endpoint answers 200 with a caveat rather than the 503 the listings use: one of the two shortfalls never clears by retrying.
The account, not the key: a workspace-scoped key reads the whole account’s totals, because usage is metered per account and billed per account. What it does not get is usage.computers, which would name machines outside its scope.
Only from and to are read. Any other query parameter is ignored rather than refused, and a bound sent twice is read from its first value.
Requires the viewer role or higher.
Request
- Base URL: https://app.mandala.computer/api/v1
- URL: https://app.mandala.computer/api/v1/usage
- Auth: HTTP bearer
Query parameters
The start of the window, RFC 3339 with a time zone — 2026-08-01T00:00:00Z. A stamp without one is refused rather than guessed at, because the zone that would be assumed is ours and not yours. Defaults to the start of the billing period, so send it together with to when you are asking about a period that has closed — to on its own is measured from the current period and refuses. When you send NEITHER bound and the billing period is longer than 62 days, the default is the most recent 62 days of it rather than a refusal, because you did not choose that window; from and to in the response say so. Records go back about 399 days, to a UTC day boundary: the refusal names the exact instant, and asking from that instant works. An older from is refused rather than answered with the zeroes an expired ledger would otherwise produce. A from at or after the present instant is a 400 too: that period has not started yet.
The end of it, same format. Defaults to now — always now, so omitting it always measures up to the present instant and never to the end of a period that has closed. A to in the future is answered as now too — the response says which instant was used. The window itself may be at most 62 days: every hypervisor replays its ledger a day at a time to answer, so a longer one THAT YOU NAMED is refused rather than quietly shortened — you chose it and can narrow it. The default window is the one exception, because you did not choose it: a billing period longer than 62 days is measured over its most recent 62 and from/to report that. Two billing periods is the pair a reconciliation compares; an older period is still readable by naming both bounds.
Response
The totals for the window, and whether anything is missing from them.
Changes
No recorded changes to this operation across all 1 revision of this API.