Track usage and budget

SupaCloud tracks two different things that limit how much agent work a workspace can do, and shows them in two separate surfaces:

• Subscription saturation — for providers connected via an OAuth subscription (a prepaid plan with rolling usage windows). You watch how full the windows are, not what you spend.
• Dollar budget — for providers billed per token via an API key. You set a monthly USD cap and watch the spend against it.

The saturation gauges live under Settings → Workspace, and the dollar-budget card lives there too. A workspace that only uses API keys sees only the budget surface; a workspace with a subscription also sees the saturation gauges.

Find usage under Reports

The Reports section in the sidebar is the home for everything you measure about a workspace. Its tabs are:

Tab	What it shows
Overview	Period-selectable charts that break down agent work
Usage	The same per-provider subscription saturation and budget figures
Delivery	The agent-profile delivery overview
Audit	The audit event log
Operations	The tenant operability view (dispatch metrics, routing, circuit breakers) — owners and admins only
Scheduled reports	The recurring reports that send themselves

For what each tab answers, see the Reports reference.

The Usage tab is where the per-provider figures described below live. Open Reports → Usage to read them in the UI, or use the usage and budget web-terminal commands shown in the later sections.

Read the Overview charts

Reports → Overview charts agent work across a period you select (for example the last day, week, or month). The breakdowns are:

• By agent — work attributed to each agent profile.
• By model — work attributed to each model.
• By run kind — for example interactive task, workflow, or backlog run.
• By project — work attributed to each project.

Each task also reports the lines of code (LOC) produced, captured by the runner, so the Overview can show LOC alongside cost and run counts.

The Overview reads GET /api/reports/overview.

Note

The usage & saturation panel is an admin/owner surface. A workspace member or viewer does not see the gauges — but the budget card is readable by every member.

Read the subscription-saturation gauges

You get one card per connected account, not one card per window. The card names the provider and the account, and each of that account’s usage windows is a row inside it. Three accounts are three cards — even when one of them has several windows and another has none.

A window is a rolling allowance that refills on a schedule. Which windows an account has depends on the provider, because SupaCloud only shows a window it can actually read:

Provider	Windows you see	Why
Anthropic (Claude)	5-hour + weekly	The provider reports both
OpenAI (Codex)	Weekly (plus a Spark pool where the plan has one)	That is what the harness reports
Google (Antigravity), GitHub Copilot	none — No quota is readable for this provider.	Nothing reports a quota for these

Note

Earlier versions showed a 5-hour and a weekly gauge for every connected subscription, because that is the shape Anthropic publishes. For Google and Copilot those gauges sat at awaiting first probe forever — a measurement that could never arrive. They are gone: the account still appears, and says plainly that no quota is readable rather than showing an empty bar.

Each window row shows:

• A fill bar with the percentage of the window consumed.
• A reset countdown on the row itself — Resets in Xh Ym, or Resets soon. Every row carries one, and it matters most when a window is full: when does it open again is then the only thing you need. A row that genuinely has no known reset says Reset unknown instead of leaving the space blank.
• Its provenance, because a measurement and an estimate are not the same claim:

Row looks like	Means
a plain bar	Measured — the figure came from the provider
bar + Estimated tag	Our arithmetic, derived from your own spend against a configured cap — not something the provider told us
a muted line, Awaiting first probe…	The window exists and a producer for it exists, but no measurement has arrived yet

And each card states when it was last measured — Measured 4 minutes ago, or Never measured. Without it a bar reading 100 % exhausted is indistinguishable from a stale reading, which is exactly the question you have when you see one.

The bar colour is the saturation band:

Band	Meaning	Colour
Under the throttling band	Comfortable headroom	Primary (teal)
Throttling soon	Within the throttling band — slow-downs are near	Warning (amber)
Exhausted	The window is at or over 100 % full	Error (red)

Caution

When a window is exhausted, runs on that subscription pause and resume automatically once the window refreshes — you do not lose the work. This is why the gauge matters: the throttling soon amber is your cue to ease off or shift work to another provider before a window fills.

Note

Connecting several accounts of the same provider gives you one card each, named by the account — the windows are never merged into a single bar, so you can read each subscription separately. The card carries the account label even when it is the only account of that provider.

Note

Some providers expose per-model windows alongside an overall one — for example Codex’s Spark budget or Claude’s Sonnet window. These are named, separate rows in the same account card, so a distinct pool reads as a distinct pool. The overall window is the one that gates whether a run pauses.

From the web terminal

The same subscription windows are available in the web terminal:

usage

It lists each subscription window with its fill percentage and an exhausted, throttling soon, or refresh in Xm marker. An API-key-only workspace is told to use budget instead; a non-admin caller is told the view is admin/owner-only.

Set a workspace budget

The AI Budget card controls the monthly dollar cap and spend for API-mode (per-token) agents.

1. Open Settings → Workspace and find the AI Budget card. It shows This month (spend so far), Remaining, and a Status badge (OK / Warning / Critical / Blocked / Unlimited).

2. Set the Monthly USD cap. Leave it empty for an unlimited (uncapped) budget.

3. Optionally set the Warning % and Critical % thresholds (when the status badge flips), the comma-separated Alert thresholds (e.g. 50,80,100) that fire notifications, and per-provider caps under Provider caps.

4. Toggle Hard stop at cap on to block new API-mode runs once the cap is reached, or off to let them continue past the cap with the status only.

5. Click Save budget.

You can also read the budget from the web terminal:

budget

It prints the status, the month spend against the cap, the remaining amount, any per-provider spend, and active alerts.

Note

The budget cap governs API-mode (pay-per-token) agents only. It does not limit a subscription provider — a subscription is capped by its usage windows, not by dollars, so its work is governed by the saturation gauges above.

Subscription windows vs. dollar budget

	Subscription window	Dollar budget
Applies to	OAuth-subscription providers (prepaid plans)	API-key providers (pay-per-token)
Limited by	Rolling usage windows (5-hour / weekly / monthly)	A monthly USD cap
You watch	How full a window is (the saturation gauges)	How much you spend against the cap
At the limit	Runs pause and auto-resume on refresh	Runs are blocked (when hard stop is on) or continue with a status
Surface	Usage & saturation panel (admin/owner) · usage	AI Budget card (all members) · budget

In short: a subscription is metered by time windows that refill, so you manage it by reading saturation and timing your work; an API key is metered by money you spend, so you manage it by setting a cap.

See also

• Schedule a report
• Web terminal command reference
• Manage secrets in the UI
• Approve or reject agent actions