Manage budgets
Create or change a Gateway budget, confirm its scope and threshold action, and verify the affected request path.
Before you begin
Required
- Organization Admin access
Use the organization's Admin role and live records; sample records cannot be changed. Team membership or a manager title does not grant edit access. A personal
cct_token identifies client requests and does not grant permission to edit organization controls. Check budget edit access and data visibility if your access is unclear. - Gateway path for testing
Confirm the client's Gateway path before testing a budget.
Create a daily budget
- Open Access & limits → Budgets and select Create budget.
- Under Applies to, choose Organization, Team or Member. Select the Team or Member from the directory.
- Set Cap (USD). Choose Day under Reset period and check Time zone. See Budget windows before comparing the cap with a reporting range.
- Choose Provider and Model filters. Unrestricted fields cover all values; a request must match both filters when set.
- For a Team budget, review Excluded Members. Other matching budgets and organization controls still apply to excluded people.
- Set Soft threshold (%) and Action at threshold. Review threshold actions and alerts before relying on an alert.
- Select Create budget and check the saved subject, cap, window, filters, action and status.
Confirm the saved budget
- Check the refreshed record.
- Send a new request after configuration reaches the supported path.
- Inspect any matching denial in Troubleshoot refusals.
A saved budget confirms configuration, not request enforcement. Compare captured reporting spend with the saved scope and window before interpreting a chart.
Change or disable a budget
- Open Edit budget on the intended record. Scope and Window stay fixed.
- Change the cap, provider/model filters, Team carve-outs, soft threshold or action. To disable the budget, set Status to Disabled; this retains its saved record.
- Select Save changes, check the refreshed record and test a new request after configuration delivery.
Choose a budget scope
Choose the contributing Organization, Team or Member, using the actual team roster. Reporting relationships do not create a parent budget or inherited allocation. Check each record's filters and exclusions; a member can match several controls.
Use workstream activity or a person's captured sessions to identify contributors within the reporting range. Workstreams group related activity; they do not establish completed work or budget authority. Neither a workstream nor a session creates a separate budget scope.
A refusal applies to a request on the managed path; it does not establish that the agent process stopped. If requests continue, check that they use the same identity and path, then inspect the matching control and denial evidence.
Compare budgets and spend
Estimated spend prices captured activity across devices over the selected reporting window. Visibility, filters, capture coverage and available pricing affect that total. Unknown cost is not zero; keep unpriced activity visible in Gateway Usage or AI spend.
Captured estimated spend is not an authoritative admission balance. Reporting and admission can differ in scope, freshness and window. Do not calculate an enforced remaining balance or budget-used percentage by subtracting captured spend from a cap. Do not add overlapping Team or workstream totals into an organization total.
Changing a cap does not change the reporting window or reconcile an invoice. Provider charges can include concurrent requests, in-flight usage, retries and incomplete responses. Reporting summaries and forecasts do not prove a request was refused; check the new request's result separately.
Threshold actions and alerts
Set Soft threshold (%) and Action at threshold when creating or editing a budget. Alert only does not block admission. Save and check the subject, cap, window, action and enabled state.
Review Active alerts and denial evidence for the last seven days, a fixed window separate from the spend chart's range. Read the matching control, subject, reason and time. A saved threshold is not a delivery receipt: confirm any notification at its destination before relying on it. Notification delivery and request enforcement are separate checks.
Related controls
Use Access & limits → Rate Limits for requests-per-minute limits and Security → Access rules for model/provider denies. A personal client token does not grant administrator access to these controls. For request authentication and response formats, see the Gateway API reference.
To repeat a baseline across teams, agree the budget cap, window, threshold action, filters and exclusions, plus any RPM limit and access restrictions. Apply those values to each intended subject and test the affected paths. Review and update each saved record separately, preserving its scope and exclusions.
Troubleshooting
| Symptom | Next action |
|---|---|
| Create or edit is disabled | Check Admin access and live records. |
| A Team or Member is missing from the picker | Refresh the directory and select an existing subject. |
| Budget changed while editing | Select Reload saved budget, then reapply the intended changes. |
| A save times out | Before creating another record, refresh the list to check whether it succeeded. |
| Saved settings and request behavior differ | Check scope, filters, carve-outs, configuration delivery and metering. |
| An expected alert is missing | Check enabled state, subject, filters, threshold and the seven-day alert window. |
| HTTP 402 continues | Check other matching budgets in Troubleshoot refusals. |
| Captured activity is missing | Check reporting range, visibility and capture coverage. |