Skip to content
CortexDocs

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

  1. Open Access & limits → Budgets and select Create budget.
  2. Under Applies to, choose Organization, Team or Member. Select the Team or Member from the directory.
  3. Set Cap (USD). Choose Day under Reset period and check Time zone. See Budget windows before comparing the cap with a reporting range.
  4. Choose Provider and Model filters. Unrestricted fields cover all values; a request must match both filters when set.
  5. For a Team budget, review Excluded Members. Other matching budgets and organization controls still apply to excluded people.
  6. Set Soft threshold (%) and Action at threshold. Review threshold actions and alerts before relying on an alert.
  7. Select Create budget and check the saved subject, cap, window, filters, action and status.
Choose the scope, daily cap, filters and threshold action before creating a budgetMobile preview. Enlarge for the full view.Open in Cortex

Confirm the saved budget

  1. Check the refreshed record.
  2. Send a new request after configuration reaches the supported path.
  3. Inspect any matching denial in Troubleshoot refusals.
Review six teams, captured spend and saved daily capsOpen in Cortex
Confirm the saved $150 daily cap, threshold action and filtersMobile preview. Enlarge for the full view.Open in Cortex

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

  1. Open Edit budget on the intended record. Scope and Window stay fixed.
  2. 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.
  3. Select Save changes, check the refreshed record and test a new request after configuration delivery.
Compare the saved $100 daily cap with the edited $150 capMobile preview. Enlarge for the full view.Open in Cortex

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.

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

SymptomNext action
Create or edit is disabledCheck Admin access and live records.
A Team or Member is missing from the pickerRefresh the directory and select an existing subject.
Budget changed while editingSelect Reload saved budget, then reapply the intended changes.
A save times outBefore creating another record, refresh the list to check whether it succeeded.
Saved settings and request behavior differCheck scope, filters, carve-outs, configuration delivery and metering.
An expected alert is missingCheck enabled state, subject, filters, threshold and the seven-day alert window.
HTTP 402 continuesCheck other matching budgets in Troubleshoot refusals.
Captured activity is missingCheck reporting range, visibility and capture coverage.