Spend, Budgets, and Billing
Keeptrusts separates spend operations into four customer-facing workflows:
- Usage for analysis and attribution.
- Budgets (
/usage/budgets) for billing-budget thresholds and declared hard-limit state. - Bills for subscription and billing-period visibility.
- Payments for payment methods, funding actions, and auto top-up when enabled.
Which surface to use
| Question | Best surface |
|---|---|
| What is driving cost, tokens, or request volume right now? | Usage |
| Which billing threshold or declared hard limit is configured? | Budgets |
| What plan, invoice, or billing-period total applies to this organization? | Bills |
| How do we manage payment methods, top-up, or auto top-up? | Payments |
Usage: operational spend analysis
Use Usage when you need to answer questions such as:
- Which provider, model, team, user, or agent is driving spend?
- Did cost spike after a rollout?
- Which slice should be exported for finance or engineering review?
Usage is the operational analysis surface. It is where teams inspect requests, tokens, cost, and attribution quality over time.
Budget controls are separate systems
The word budget appears on several surfaces. They store different records and do not all participate in the same request path.
| Control | Configure or inspect it in | Current request-path boundary |
|---|---|---|
| Billing budget | Console Usage → Budgets | Stores billing thresholds, alert settings, and declared hard-limit state. Verify the exact deployment path before treating it as a gateway block. |
| Scope spend budget | kt spend budget or /v1/budgets | Tracks organization, team, user, or key spend. A standalone gateway with an event sink can use remaining headroom; a connected gateway does not load these scope records for routing. |
| Provider budget | kt spend provider-budget | Participates in provider-headroom checks for configured gateway traffic. A target also needs pricing metadata for estimated-cost steering. |
| Governed API-token budget | API Tokens or kt token ... --max-budget | Depletion is checked for requests authenticated by that token. |
| Unified Access budget policy | Unified Access policy APIs | Stored effective-policy and simulation result only; the live wallet reservation path does not enforce it. |
| Wallet balance | Bills → Payments | Insufficient available balance is the active funding stop for managed Unified Access traffic. |
This distinction is why a value shown in one budget view must not be presented as proof that another request path is enforced. See Unified Access Budgets for the simulation-only policy boundary.
Budgets: thresholds and declared limits
Use Budgets when you need to:
- Set or review budget amounts.
- Review declared hard-limit and alert-threshold state.
- Scope a budget to the organization, a team, a user, or an agent where supported.
Budgets are the billing-governance workflow. Use them when the question is about configured thresholds and state, not about invoices. Use the table above to identify which control actually owns the request path you are diagnosing.
Bills: subscription and billing-period visibility
Use Bills when you need to understand:
- Current subscription state.
- Billing-period totals.
- Invoice and closeout visibility.
- Service-level billing breakdown.
Bills answers commercial questions about what the organization owes or has already been billed.
Payments: payment methods and funded balance operations
Use Payments when you need to:
- Add or update payment methods.
- Manage top-up or auto top-up behavior when your organization uses funded balance.
- Confirm payment readiness before enabling or expanding production traffic.
If your deployment uses funded balance controls, Payments is the surface that supports keeping the organization able to spend.
How teams usually split ownership
- Engineering uses Usage, request IDs, and
kt eventsorGET /v1/eventswith requiredsinceto correlate cost changes with rollout changes. Capture-enabled History adds session context only when the configured mode and platform retention policy make it available. - Operations uses Budgets and Payments to monitor configured limits and funding readiness.
- Finance uses Bills plus exported usage slices for reconciliation and review.
When traffic is affected by spend controls
If a request cannot proceed and the error indicates a spend or funding issue:
- Preserve the response code, error code, request ID, token ID, provider, and model.
- Inspect the active control for that path: governed token depletion, provider budget, or managed wallet balance.
- Use Budgets for billing-threshold context, but do not assume that a stored billing or Unified Access policy caused the rejection.
- Check Payments if the organization depends on funded balance.
- Re-run the request only after the owning control and its approved change are understood.