Managing Model Spend with Budgets
Every time an agent calls a large language model (LLM), Solace Agent Mesh records what the call cost. A budget sets a limit on that cost for each period. A budget's period is one calendar month: every budget resets at 00:00 Coordinated Universal Time (UTC) on the first day of each month. The Agent Mesh budget limits the total spend of the whole deployment, and a user budget limits the spend of each user assigned to it. When a budget is spent, Agent Mesh refuses new model work until the budget resets or you raise its limit.
This page covers how Agent Mesh measures model spend, how budgets apply, how to manage budgets from the Budgets and User Management pages, and how to review spend on the Cost and Token Usage page in the Agent Mesh UI. To manage budgets as version-controllable YAML instead, see Managing Budgets with the CLI.
How Agent Mesh Measures Model Spend
Agent Mesh prices each LLM call from the rates, in US dollars (USD) per 1,000,000 tokens, on the model configuration that the call used. It prices input, output, cache-read, and cache-write tokens separately. For more information, see Pricing Models.
Keep the following points in mind when you review spend:
-
A model with no price set is unpriced, not free. Agent Mesh records the tokens of a call to an unpriced model but no cost, so the call does not count toward any budget.
-
Agent Mesh prices a call when it records the call, using the model's rates at that moment. A price change affects only calls that Agent Mesh records after the change.
-
Agent Mesh keeps spend records for 90 days and then deletes them.
For more information, see Spend That Budgets Don't Count. For more information about how Agent Mesh prices cache writes and image and audio input, see Pricing Models.
How Budgets Apply
Every budget has a budget scope: Agent Mesh or User.
-
The Agent Mesh budget limits the total spend of the deployment, across all users. A deployment has exactly one Agent Mesh budget. You can change its limit, but you cannot delete it.
-
A user budget limits the spend of each user assigned to it. Every user on the budget can spend up to its limit in a period, and Agent Mesh does not combine their spend. One user budget is the default, and it applies to every user who has no budget assigned, including system users, such as the one that evaluations run as.
Both limits apply at the same time: a user can make requests only while neither the Agent Mesh budget nor their own budget is spent.
Every deployment starts with two budgets, both unlimited and with no alert threshold: the Agent Mesh budget, named Agent Mesh, and the default user budget, named Default User.
Desktop bundle — The desktop bundle runs as a single user, so the Budgets page does not offer user budgets. That user stays on the unlimited default user budget, so the Agent Mesh budget is the only limit that applies. For more information about the desktop bundle, see Installing the Desktop Bundle.
Following the Default and Pinning
A user either follows the default user budget or is pinned to a budget:
-
A user with no assignment follows the default. When you make another budget the default, these users move with it.
-
A user assigned to a budget is pinned to it, including when that budget is the current default. A pinned user stays on their budget when the default changes.
To return a pinned user to following the default, remove their assignment.
Limits, Alert Thresholds, and Additional Amounts
A budget has the following settings:
-
Limit (USD): the most the budget allows in one period, with at most two decimal places. A budget can instead be Unlimited.
-
Alert Threshold: an optional whole number from 1 to 100 that sets the percentage of the limit at which a budget counts as approaching its limit. Agent Mesh does not refuse any work when spend reaches the alert threshold. An unlimited budget cannot have an alert threshold.
When spend reaches a budget's alert threshold, and again when it reaches the limit, Agent Mesh notifies the following users:
-
Each user receives a notification about their own budget.
-
Users who hold
budget:*:updateorbudget:*:assignreceive a notification about the Agent Mesh budget and about the budgets of system users.
Notifications are an Early Access feature.
A user can also have an additional temporary amount, which raises that user's limit until the end of the current period. For more information, see Granting an Additional Temporary Amount.
Prerequisites
Before you set budgets, complete the following tasks:
-
Price your models. Calls to an unpriced model do not count toward any budget. For more information, see Configuring Models.
-
Make sure you have the budget scopes. Viewing budgets requires
budget:*:read. Viewing the Cost and Token Usage page and a budget's View Details page requires*:*:read_usage. You can add both scopes to a role. Creating, editing, deleting, and assigning budgets require scopes that only super administrators and the built-insam_managerrole hold. For more information, see Budget and Usage Scopes.
Opening the Budgets Page
On the navigation bar, expand System Settings and select Budgets.
The page has two sections:
-
Agent Mesh Budget shows the Agent Mesh budget's Limit (USD), Alert Threshold, and Period.
-
User Budgets lists every user budget with its limit and alert threshold, and marks the default budget with a Default badge.
Setting the Agent Mesh Budget
-
On the Budgets page, open the menu on the Agent Mesh Budget section and select Edit Budget.
-
In Limit (USD), enter the limit, such as
5000or5000.50. To remove the limit, select Unlimited instead. -
(Optional) In Alert Threshold, enter a percentage from 1 to 100.
-
Click Save.
Managing User Budgets
You create, view, edit, and delete user budgets from the User Budgets section of the Budgets page.
To view a budget, open its menu and select View Details. The budget's page shows its settings and this month's spend for each user the budget applies to. View Details appears only if you hold *:*:read_usage. To change a budget's name, limit, or alert threshold, open its menu and select Edit, then click Save. You cannot change the budget scope after you create the budget.
Creating a User Budget
-
On the Budgets page, click Create User Budget.
-
Enter a Name. A name is 3 to 255 characters and must be unique. Agent Mesh treats names that differ only in letter case as the same name.
-
In Limit (USD), enter the limit for each user, or select Unlimited.
-
(Optional) In Alert Threshold, enter a percentage from 1 to 100.
-
Click Create.
A new budget applies to no one until you assign users to it or make it the default.
Deleting a User Budget
Open the budget's menu and select Delete, then confirm. The Delete option appears only if you hold both budget:*:delete and budget:*:assign.
When you delete a budget, its users revert to the default user budget. You cannot delete the default user budget; make another budget the default first.
Changing the Default User Budget
-
Open the menu of the budget you want as the new default and select Set as Default.
-
Review the Change Default User Budget dialog, which compares the Current Default and New Default.
-
Click Save.
Users who follow the default move to the new default. Users pinned to the old default stay on it, and the old default remains available as an ordinary budget.
Assigning Users to a Budget
-
On the Budgets page, click Manage Assignments on the budget's row.
-
In Add users by name or email, search for a user and select them. If the user is on another budget, saving moves them to this one.
-
To remove a user, click the Remove icon next to their name, or the Unpin icon on the default budget.
-
Click Save.
You can save at most 1,000 changes at a time. Without budget:*:assign, the button reads View Assignments and the dialog is read-only.
Adding a user to the default budget pins them to it, so they stay on it even if the default changes. Removing a user from any budget returns them to following the default.
The Manage Assignments dialog lists only people who have signed in. To assign a budget to someone who has not signed in yet, use sam config apply. Agent Mesh applies the assignment when the person first signs in. For more information, see Managing Budgets with the CLI.
Managing One User's Budget
The User Management page shows each user's budget in the Budget column and lets you change it for one user at a time. The User Management page is visible only to a super administrator.
To list only the users on one budget, use the Any Budget filter.
Changing a User's Budget
-
On the User Management page, open the user's menu and select Manage Budget.
-
In Budget, select the budget to pin the user to. To return the user to following the default, click Revert to Default.
-
Click Save.
Granting an Additional Temporary Amount
An additional temporary amount raises a limit until the end of the current period, without changing the budget itself. For example, you can let one user finish a large job this month while the other users on their budget keep the usual limit.
-
On the User Management page, open the user's menu and select Manage Budget.
-
In Additional Temporary Amount (USD), enter the amount, such as
100or100.50. -
Click Save.
The following rules apply to an additional temporary amount:
-
The amount must be greater than 0 and no more than $100,000.00.
-
A new amount replaces the current one; it does not add to it. To cancel an amount, clear the field and save.
-
You cannot grant an additional amount on an unlimited budget.
Reviewing Cost and Token Usage
The Cost and Token Usage page shows what model calls cost across the deployment. To open it, expand Signals & Usage on the navigation bar and select Usage. The page is visible only to users who hold *:*:read_usage.
The page has the following sections:
-
Overview shows the total spend for the selected Period, compared with the previous period, and the token cost for each day or week. You can select a period within the last 90 days.
-
Usage by Type breaks down spend on the Agents, Workflows, Users, and Models tabs. Select a row to see its cost over time and its activities. The desktop bundle has no Users tab.
If any calls in the selected period used an unpriced model, a banner shows how many, because the page does not include their cost.
Viewing your own spend requires no scope. On the navigation bar, select User Account, then select Usage in the User Account Settings dialog to see this month's spend against the budget that applies to you, and your spend in each of the last three months.
What Happens When a Budget Is Spent
A budget is spent when the spend in the current period reaches its limit plus any additional temporary amount. For a user budget, Agent Mesh compares each user's own spend with the limit. An unlimited budget is never spent, and a budget with a limit of 0 is spent from the start of the period.
When the Agent Mesh budget is spent, Agent Mesh refuses model work for everyone. When a user's own budget is spent, Agent Mesh refuses model work for that user, while other users continue. Agent Mesh checks work that runs as a system user against that system user's budget.
While a budget is spent, Agent Mesh refuses new requests at every entrypoint. For a request that is already running, it refuses the next LLM call: the call in progress finishes, and then the request stops. Agent Mesh also refuses the following LLM calls:
-
Calls that tools make through Agent Mesh.
-
Calls that Agent Mesh makes for you, such as calls for the AI Assistant, evaluations, and model connection tests.
Agent Mesh does not refuse calls that tools, Model Context Protocol (MCP) servers, and external agents make with their own API keys, even when a budget is spent. To track and limit that spend, give these tools API keys that no model configuration uses, so that your provider reports their usage separately, and set spending limits with the provider.
The refusal message names whose budget is spent and when it resets, but not the amount. When the Agent Mesh budget is spent, the message is:
Sorry, I can't take new requests right now: this deployment's usage budget is used up until 1 December 2026 00:00 UTC. Contact your administrator if you need it sooner.
When the user's own budget is spent, the message begins "Sorry, I can't take new requests from you right now: your usage budget is used up until". When a system user's budget is spent, the message begins "Sorry, I can't take new requests right now: the usage budget is used up until" and names the system user.
The chat page shows a banner while the user's own budget or the Agent Mesh budget is spent, and the refusal message appears at the refused turn.
A refusal ends when the budget resets at the start of the next month. To end it sooner, raise the budget's limit, make the budget unlimited, grant an additional temporary amount, or move the user to a budget that is not spent. Agent Mesh usually applies such a change within a few seconds.
Spend That Budgets Don't Count
Budgets count only the spend that Agent Mesh records and prices. Agent Mesh does not count spend in the following cases, so your provider bill can be higher than the spend that Agent Mesh shows:
-
Agent Mesh records no cost for calls to an unpriced model. To record a model as costing nothing, set both its input and output rates to
0. For more information, see Pricing Models. -
When an agent's configuration includes its own model connection details, Agent Mesh records the agent's calls as unpriced.
-
When an LLM-as-a-Judge evaluator names a provider's model, such as
openai/gpt-4o-mini, that matches no model on the Models page, Agent Mesh records the evaluator's calls as unpriced. For more information, see LLM-as-a-Judge Evaluators. -
Agent Mesh does not record calls for which the provider reports no token usage.
-
Agent Mesh does not record calls that a tool, MCP server, or external agent makes with its own API key, such as the calls that the built-in image generation, image editing, audio transcription, and text-to-speech tools make. For more information about these tools, see Image and Audio.
Troubleshooting
For requests that Agent Mesh refuses because a budget is spent, see Requests Refused Because a Budget Is Spent.
Requests Are Refused Because Usage Budgets Cannot Be Checked
Agent Mesh refuses new requests with the following message:
Sorry, I can't take new requests right now: this deployment's usage budgets can't be checked at the moment. Please try again in a few minutes.
The Entrypoint Executor has not yet received the current budget state from the Platform service. This delay occurs after the Entrypoint Executor restarts while any budget has a limit, and at the start of a month for the users of a budget that was spent. Requests that are already running continue. For more information about these components, see How Agent Mesh Manages Workloads and Platform Service.
To resolve this issue, perform these steps:
-
Wait a few minutes and try again.
-
If the refusals continue, confirm that the Platform service is running.
What Next?
-
To set the rates that budgets are measured against, see Configuring Models.
-
To manage budgets and their assignments as YAML, see Managing Budgets with the CLI.
-
To give a role the budget scopes, see Budget and Usage Scopes.