Usage & billing
The Usage page shows what your organization is spending on agent activity — model requests, agent runs, tool calls, and related surfaces — and lets admins set budget policies to cap internal spend. Customer-visible contracts define entitlement; org budgets define house rules inside that entitlement.
Reading usage
Usage is shown over a selectable time window (7 / 30 / 90 days or custom) with rollups by org, team, project, member, model, and repository where your plan exposes attribution.
Included vs on-demand
Two buckets appear on every org usage summary:
The included allowance (monthlyUsdCap from entitlements) is set by platform operators in
the Console. Admins see the same cap on Usage and in Settings budget dialogs as the reference
line for "plan included."
What drives spend
Use filters for surface (desktop, CLI, cloud), project, and model when investigating spikes after a release or CI change.
Usage reservations at run time
Before a cloud agent run starts, agents-api.4rged.ai calls reserveAgentRunUsage to
preflight spend against org budget and contract entitlements. If the reservation is denied, the
API returns 402 Payment Required with a usageReservation payload explaining the block —
no job is enqueued. Successful reservations record estimated_usd and reconcile to reconciled_usd
when the run completes; Sentinel and the operations summary aggregate these rows for the last
24 hours.
Budget policies
Budgets are your internal caps — stricter than contract, never looser. Enforcement modes map to how the platform responds as you approach or exceed a cap:
Org settings UI often expresses on-demand behavior as unlimited (warn), fixed cap (soft
stop), or strict cap (hard stop) — saved server-side as monthlyUsdCap plus enforcement
enum.
Setting a budget policy
Open Manage budget
From Usage (budget meter card) or Settings → Organization, open Manage budget. Requires admin or super admin.
Choose cap mode
Enter a USD value at or below your contract ceiling. Setting above entitlement may clamp to contract maximum in UI.
Set enforcement
Pick how aggressively to enforce as usage approaches the cap:
- Warn for learning phases and internal dogfood orgs
- Soft stop when you want to stop on-demand burn but avoid hard outages mid-incident
- Hard stop for strict cost control in production orgs
Save and communicate
Save the policy — it applies organization-wide and is audited. Notify team leads when moving from warn → hard stop so CI and cloud automations are expected to fail closed.
Team and project budgets
Enterprise layouts may allocate subsets of org budget:
Team/project budgets narrow org capacity — they cannot grant spend beyond org policy or contract.
Admin walkthrough: monthly review
Compare to included allowance
On Usage, confirm Included consumption vs plan allowance. If included is consistently exhausted mid-month, request capacity from your operator via Console — do not only raise internal budget without entitlement.
Inspect on-demand drivers
Sort attribution by project and model. Common findings: CI using a reasoning model, cloud migration project, or new team without team-level cap.
Review denials
Spike in denials may indicate model policy misconfiguration rather than budget — cross-check Model control.
Adjust policy or catalog
Tighten model groups, lower project budgets, or switch CLI default to a lower cost class before raising org cap.
Export
Export CSV for finance or chargeback when your plan includes usage exports.
Budget vs contract — quick reference
Budgets are your internal house rules (set by admins). Contracts and capacity are your entitlement (set by operators in the Console). Budgets can be stricter than your contract, never looser.
Hard stop blocks new runs that would incur spend — scheduled CI jobs fail until the cap resets or an admin raises policy. Prefer warn or soft stop during pipeline bring-up.