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)

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

Each connected subscription provider renders one gauge per usage window. A window is a rolling allowance that refills on a schedule:

Window	What it measures
5-hour window	The rolling 5-hour allowance
Weekly	The rolling weekly allowance
Monthly	The rolling monthly allowance (when the plan has one)

Each gauge shows:

• A fill bar with the percentage of the window consumed.
• A refresh countdown — Resets in Xh Ym, or Resets soon when a window is due imminently.
• An Estimated tag when the figure comes from telemetry rather than a hard limit reported by the provider — treat it as a lower-confidence estimate.

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

When you connect several accounts of the same provider, each connected account gets its own set of gauges, labelled with the account’s email — the windows are no longer merged, so you can read each subscription’s saturation separately.

Note

Some providers expose per-model windows alongside an overall one — for example Codex’s Spark budget or Claude’s Sonnet window. Each renders as its own gauge next to the account’s overall window, so you can read a single model’s saturation separately. 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