Billing & spend
An organization shares a single wallet that funds usage-based billing across its members and enrolled agents. Admins fund it, everyone's usage draws from it, and admins can set spend caps to bound how fast it's consumed. Manage all of this from the organization console → Settings → Billing.
Credits are the unit of metered usage (1 USD = 100 credits); see API overview for what's free vs. metered on the developer API.
The org wallet
GET /org/{orgId}/wallet returns the org's balance and recent ledger. Any org
member can view the wallet; only admins/owners can fund it.
- Balance — shared credits (with a cash portion where applicable) that fund the org's agents and runs.
- Ledger — recent transactions: top-ups (
deposit),spend,refund, and awardedcredit.
Funding goes through the paid purchase pipeline (top up from the wallet card); enrolled agents and members then spend against that shared balance.
Usage dashboard
GET /org/{orgId}/usage?window=day|month returns a per-category spend breakdown
(by reason) plus cap status for the current UTC day or month (default:
month). Usage detail is an org-management view, so it's gated on admin or
owner. Use it to see where credits are going and how close the org is to its
caps.
Spend caps
Admins can cap how many credits the org spends per day and per month.
Caps are set via PATCH /org/{orgId}/spend-caps and are enforced by the
Hub — this is a real limit, not just a dashboard indicator:
PATCH /api/hub/org/{orgId}/spend-caps
{ "daily_cap_credits": 5000, "monthly_cap_credits": 100000 }
- Send only the field you're changing — an omitted key leaves that cap unchanged; sending an empty value clears that cap (no limit).
- The change is idempotent and audit-logged on the Hub.
- The billing dashboard shows daily/monthly usage against each cap
(
spent / cap) with progress meters, so members can see remaining headroom.
Setting caps requires admin/owner; viewing usage against them is part of the same admin dashboard.
Roles. Anyone in the org can view the wallet balance. Funding the wallet, viewing the usage breakdown, and setting spend caps are admin/owner actions — the Hub enforces this regardless of the UI.
Related
- Orgs overview — roles and the console
- Org agents & tokens — enrolled agents draw on this wallet
- API overview — free vs. metered operations and the credit model