AI Cost Budgets

Budgets cap AI spend at three independent tiers — Global, Per-Workspace, and Per-Task — so a runaway agent or a busy week never produces a surprise bill. Spend is tracked in real time from the same per-message cost audit shown across the app; when a blocking limit is hit, Polygent stops the offending session and notifies the right people.

The three tiers

Tier	Scope	Set under	Opt-out?
Global monthly	All workspaces combined	Settings → General → AI Cost Budget	Yes (block toggle)
Workspace monthly	One workspace	Workspace → Budgets	Yes (per-workspace block toggle)
Per-task	A single ticket	Create Ticket modal, or workspace default	No — always enforced

Each tier is independent. A run is allowed only if every enforced tier still has headroom.

How spend is measured

• Monthly spend (global or workspace) is the sum of all AI cost recorded in the current calendar month (UTC). The window rolls over automatically on the 1st — there is no reset job to schedule.
• Per-task spend is the sum of all AI cost across every session attached to that ticket.
• Post-processing passes (Insights, Code Review, Verification) still record their cost, but they never cancel the parent session.

Enforcement

Budgets are checked at two moments:

1. Before a run starts — if an enforced tier is already at or over its limit, the session is canceled with a system message explaining why, and the agent is never dispatched.
2. During a run — after each usage update is recorded, Polygent re-evaluates the tiers. If a blocking limit is breached mid-run, the session is moved to Canceled and a system message is posted into the chat.

For providers that support a native per-session cost cap (Polygent Code and Claude Code), Polygent also passes the remaining budget down so the agent stops itself before the next model call. Other providers are enforced on the Polygent side after each usage update.

Warnings

Before a limit is reached, Polygent sends a single inbox warning when spend crosses the warning threshold (default 80%) of any configured limit. Warnings are de-duplicated per tier for a few hours so you get one heads-up, not a stream. Global warnings go to admins; workspace and per-task warnings go to that workspace's members.

Configure a global budget

1. Open Settings → General → AI Cost Budget (requires the Manage Settings permission).
2. Set Global Monthly Budget (USD).
3. Set the Warning Threshold (%) (1–100, default 80).
4. Toggle Block when exceeded on to hard-stop runs, or off to warn only.

Configure a workspace budget

1. Open the workspace and go to the Budgets tab.
2. Set Monthly Budget (USD) for the workspace.
3. Optionally set a Default Per-Task Budget (USD) — applied to any ticket that doesn't set its own cap.
4. Toggle Block when exceeded for the workspace.

The Budgets tab also shows current month-to-date spend against each limit with a progress bar that shifts from green to amber to red as you approach the cap.

Set a per-task budget

When creating a ticket, fill in Per-Task AI Budget (USD). This cap is always enforced — it overrides the workspace default and ignores the block toggles, because it is an explicit, ticket-scoped decision. Leave it blank to fall back to the workspace's default per-task budget (if any).

What happens when a budget is hit

• The active session is canceled (not paused) with an explanatory system message in the chat.
• An inbox notification is sent — to admins for a global breach, or to workspace members for a workspace/task breach.
• The session is not auto-restarted. Once an admin raises the limit (or disables the block toggle), the next message you send passes the pre-flight check and the session resumes normally.

Where to watch spend

Place	Shows
Workspace → Budgets	Month-to-date workspace and global spend vs. limits
Settings → General	Global monthly budget configuration
Statistics → Cost & Tokens	Spend cards for global and the selected workspace
Session header / Ticket detail	Aggregate USD cost for that one session or ticket

Examples

Cap a noisy experiment A team wants to let a junior engineer try the AI Planner and a few Develop sessions without risk. Set the workspace monthly budget to $50 with block when exceeded on. Sessions stop the moment the workspace hits $50 that month; the engineer gets an inbox notice at $40 (80%).

Protect against a single expensive ticket A large refactor ticket could loop for hours. Set its Per-Task AI Budget to $15 when creating it. Even on Auto mode with a workflow, the ticket's sessions stop once $15 of AI cost accrues — no matter the workspace or global headroom.

Warn-only governance for the whole org Leadership wants visibility but not hard stops. Set a global monthly budget of $2,000 with block when exceeded off and the threshold at 75%. Admins get an inbox warning at $1,500; nothing is ever canceled, but the number is impossible to miss.

Per-team caps under one org ceiling Give each workspace its own $300 monthly budget (block on), and set a $2,000 global budget (block on) as a backstop. Any one team is capped at $300, and the org can never exceed $2,000 even if a new workspace is added mid-month.

Permissions

Action	Requires
View workspace budget & spend	workspaces.view
Edit workspace budget	workspaces.edit
View / edit global budget	settings.view / settings.manage
Set a per-task budget on a ticket	tickets.manage

See Also

• Statistics — cost and token analytics
• Agent Providers — which providers support native per-task cost caps
• Tickets — per-ticket configuration