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.	Management → System → General → Global AI Cost Budget
Workspace monthly	Recorded usage in one workspace in the current UTC calendar month.	Workspace → Budgets
Ticket	Recorded usage across the ticket's Plan, implementation sessions, and AI merge-conflict resolution.	Ticket Edit action, with an optional workspace default.

A blank limit means no limit at that scope; a limit of 0 blocks every run in that scope. An explicit ticket limit overrides the workspace's default per-task limit; with neither set, the ticket has no task limit. Every configured limit is enforced — there is no advisory mode. All 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 model's configured pricing and the usage the provider reports, so compare Polygent totals with provider billing when financial reconciliation is required. A custom model whose cost is Unknown is blocked whenever any budget applies, because its spend cannot be measured; set its pricing or classify it as Free or Unmetered in Models & Backends.

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 Management → System → General → Global AI Cost Budget with Manage Settings.
2. Enter Global Monthly Budget (USD).
3. Set Warning Threshold (%) from 1 to 100; the default is 80. The threshold applies to global, workspace, and ticket limits.
4. Save and verify the displayed month-to-date spend.

The Block when global budget exceeded switch does not currently make the limit advisory; a configured global limit always blocks.

Workspace budget

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

1. Open the workspace and select the Budgets tab (requires Edit Workspaces).
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 a Pending or Queued ticket and select Edit (requires Manage Tickets).
2. Enter Per-Task AI Budget (USD, optional).
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 warning percentage of an applicable limit, Polygent creates an inbox warning; when a limit is reached, it sends a separate AI Budget Exceeded alert. Global alerts go to administrators; workspace and ticket alerts go to every member of the workspace. Alerts for the same scope are sent at most once every few hours (the window restarts when the API restarts), and one usage update produces at most one warning, for the narrowest scope crossed.

Enforcement and recovery

Budget enforcement checks headroom before new work starts and stops a running agent when a limit is reached.

• A run starts only when every applicable scope has remaining headroom. Runs in progress hold part of that headroom, so parallel runs cannot jointly overspend; a new run can therefore be blocked before earlier runs have reported all their cost.
• A run blocked before it starts posts a "Session stopped" system message in the session with the blocking scope; no inbox alert is sent.
• When a limit is reached during a run, the session displays Stopping until the host confirms that the agent exited, then returns to Waiting.
• The current model call may complete before its final cost is known, so actual spend can exceed a limit by that call's cost.
• For ticket implementation, the ticket then continues its normal flow (for example to Developer Approval) with the work completed so far.
• If the host does not confirm the stop in time, the session enters recoverable Error and the ticket does not advance. Check the assigned Session Worker and verify that the run ended before restoring the session.
• 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.
Management → System → General	Review global limit and warning threshold.
Statistics → Cost & Tokens → Budgets	Review cost trends and budget usage; select a workspace to see global month-to-date spend.
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, other runs in progress, and whether the model's cost is Unknown.
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.