AI Cost Budgets

AI cost budgets place USD limits on recorded model usage at global, workspace, and ticket scopes. For model setup that affects cost reporting, see Models & Backends.

Budget scopes

Each configured scope is enforced independently, and a run requires headroom in every applicable scope.

Scope	Applies to	Configure at
Global monthly	Recorded usage across all workspaces in the current UTC calendar month.	Settings → General → AI Cost Budget
Workspace monthly	Recorded usage in one workspace in the current UTC calendar month.	Workspace → Budgets
Ticket	Recorded usage across sessions linked to one ticket.	Ticket Edit action, with an optional workspace default.

A blank limit means no limit at that scope. An explicit ticket limit overrides the workspace's default per-task limit. All monetary values are USD and must be zero or greater.

Cost accounting

Budget accounting uses the cost reported for model usage and the workspace or ticket associated with that usage.

Monthly windows roll over at the start of each UTC calendar month; no reset job is required. Ticket spend accumulates across all sessions linked to the ticket. Cost reporting depends on the selected model supplying usable pricing and usage data, so compare Polygent totals with provider billing when financial reconciliation is required.

Configure budgets

Budget configuration sets hard limits and the warning point used before a limit is reached.

Global budget

The global budget is the organization-wide monthly ceiling.

1. Open Settings → General → AI Cost Budget with Manage Settings permission.
2. Enter Global Monthly Budget (USD).
3. Set Warning Threshold (%) from 1 to 100; the default is 80.
4. Save and verify the displayed month-to-date spend.

Workspace budget

A workspace budget limits one team's monthly usage and can provide a default ticket limit.

1. Open the workspace and select Budgets with workspace edit permission.
2. Enter Monthly Budget (USD).
3. Optionally enter Default Per-Task Budget (USD).
4. Save and verify both workspace and global progress.

Ticket budget

A ticket budget is the most precise limit for implementation work.

1. Open the ticket and select Edit.
2. Enter Per-Task AI Budget (USD).
3. Save and confirm that ticket spend and the limit appear in ticket details.

Leave the field blank to use the workspace default when configured. Set an explicit value to override that default.

Warnings

Warnings provide advance notice without stopping work.

When recorded spend crosses the configured percentage of an applicable limit, Polygent creates an inbox warning. Global warnings target administrators; workspace and ticket warnings target relevant workspace members. Warning delivery is de-duplicated, so repeatedly crossing the same threshold may not create a new notification immediately.

Enforcement and recovery

Budget enforcement prevents new work when a limit is exhausted and stops an active run after newly recorded usage crosses a limit.

• Before a run, every applicable configured budget is checked.
• During a run, limits are re-evaluated as usage is recorded.
• The current model call may complete before its final cost is known, so actual spend can exceed a limit by that call's cost.
• Ticket implementation follows its normal post-implementation workflow when budget enforcement ends the run.
• Raising or clearing the blocking limit allows a later message or retry to proceed; Polygent does not silently restart the stopped work.

To recover:

1. Read the session system message to identify the blocking scope.
2. Compare current spend with global, workspace, and ticket limits.
3. Confirm that increasing or clearing the limit is authorized.
4. Update the narrowest blocking scope.
5. Resume by sending a new message or retrying the intended ticket action.
6. Monitor the next usage update to confirm that the correct budget applies.

Monitoring

Budget monitoring combines configuration views with recorded cost reporting.

View	Use
Workspace → Budgets	Compare workspace and global month-to-date spend with their limits.
Settings → General	Review global limit and warning threshold.
Statistics → Cost & Tokens	Review cost trends and selected-workspace totals.
Ticket details	Review ticket spend against an explicit or default task limit.
Session details	Review recorded session cost and applicable task budget.

Provider invoices remain the financial source of truth. Investigate material differences in model pricing configuration, missing usage data, workspace attribution, or reporting period boundaries.

Operational guidance

Budget policy should leave enough headroom for one final model call while still containing risk.

• Set a global backstop even when every workspace has a budget.
• Set workspace limits according to team ownership and expected monthly activity.
• Use ticket limits for experimental, long-running, or high-risk work.
• Set warning thresholds early enough for an operator to respond.
• Review budgets after changing model selection or workload volume.
• Do not interpret a warning as a hard stop; only the configured limit blocks work.

Troubleshooting

Budget troubleshooting starts by identifying scope, time window, and cost attribution.

Symptom	Resolution
Run is blocked although the ticket has headroom	Check workspace and global monthly limits; all applicable scopes must have headroom.
Ticket uses an unexpected limit	Check for an explicit ticket value; it overrides the workspace default.
Spend exceeds the configured limit	A model call can finish before its cost is recorded. Account for one-call overshoot when setting the ceiling.
Warning was not received	Confirm a limit exists, the threshold was crossed, the recipient has the relevant role or workspace membership, and the warning was not recently de-duplicated.
Monthly spend did not reset at local midnight	Monthly budgets use UTC calendar boundaries.
Cost appears missing or inaccurate	Verify the model reports usage and pricing, then compare the same UTC period with provider billing and Statistics.
Work does not restart after increasing a limit	Send a new session message or retry the ticket action; stopped work is not restarted automatically.