Agent Budget

Monitor token usage, set spending caps, and manage budget alerts for this agent.

Overview
How It Works
Key Concepts
Best Practices
Troubleshooting
Related Pages

Overview

For Everyone

AI agents cost money — every message, every tool call, every API request uses tokens that translate to real dollars. The Budget tab is your financial dashboard. It shows how much the agent has spent today and this month, lets you set spending caps so the agent can't run up a surprise bill, and alerts you when spending approaches your limits.

For Developers

Three endpoints power this section:

GET /agents/:id/usage — Current usage metrics (tokens, cost, sessions, errors for today and month).
GET /agents/:id/budget — Budget configuration (returns { budgetConfig: { limits: { dailyTokens, dailyCost, monthlyTokens, monthlyCost } } }).
GET /budget/alerts?agentId=… — Active budget alerts.

Saving: PUT /agents/:id/budget with { dailyTokens, dailyCost, monthlyTokens, monthlyCost }. Acknowledging alerts: POST /budget/alerts/:id/acknowledge.

How It Works

Load — Usage, budget config, and alerts are fetched in parallel on mount.
Monitor — The stats grid shows six key metrics. Progress bars visualize usage against limits.
Configure — Click "Edit Budget" to set daily and monthly limits for both tokens and cost.
Alert — When usage approaches or exceeds limits, alerts appear in the alerts table. Acknowledge them to clear the notification.
Enforce — When a limit is reached, the agent is automatically paused to prevent overspending.

Key Concepts

Usage Statistics

Six stat cards provide real-time usage data:

Metric	Description
Tokens Today	Total tokens consumed today (input + output). Resets at midnight UTC.
Tokens This Month	Total tokens consumed this calendar month.
Cost Today	Dollar cost of today's token usage.
Cost This Month	Dollar cost of this month's token usage.
Sessions Today	Number of agent sessions started today.
Errors Today	Number of errors today. Shown in red if > 0.

Budget Limits

Four configurable spending caps:

Daily Token Limit — Maximum tokens per day. Set to 0 for unlimited.
Daily Cost Limit ($) — Maximum dollar spend per day. Supports decimal values (e.g., $5.00).
Monthly Token Limit — Maximum tokens per calendar month.
Monthly Cost Limit ($) — Maximum dollar spend per month.

When any limit is reached, the agent is automatically paused. It requires a manual resume or limit increase to continue.

Progress Bars

When budget limits are configured, progress bars visualize current usage against each limit. The bars show:

The limit label (e.g., "Daily Tokens")
Current value vs. total limit
A visual bar that fills and changes color as usage increases

Only configured limits (non-zero) are displayed.

Budget Alerts

The system generates alerts at different thresholds:

Alert Type	Trigger	Impact
Warning	Usage reaches ~80% of limit	Notification only. Agent continues.
Critical	Usage reaches ~95% of limit	Notification. Consider pausing non-essential work.
Exceeded	Limit reached	Agent automatically paused. Requires intervention.

Each alert shows:

Time — When the alert was triggered.
Type — Warning, Critical, or Exceeded.
Budget Type — Tokens or Cost.
Current / Limit — Actual usage vs. the configured limit.
Status — Pending or Acknowledged.
Ack Button — Click to acknowledge and dismiss the alert.

Best Practices

Start with conservative daily limits — Monitor usage for a week, then adjust. It's easier to raise limits than to deal with a surprise bill.
Always set a monthly cost limit — This is your safety net. Even if daily limits are generous, the monthly cap prevents runaway spending.
Monitor the errors metric — High error counts often mean wasted tokens on failed operations. Fix the errors to reduce costs.
Acknowledge alerts promptly — Unacknowledged alerts clutter the view. Acknowledge them after reviewing and taking appropriate action.
Use cost limits, not just token limits — Different models have different per-token costs. A cost limit is a more accurate spending control.
Review sessions count — High session counts relative to useful output may indicate the agent is being triggered too frequently or spinning up unnecessary sessions.

Troubleshooting

Agent paused due to budget but usage seems low

Check which specific limit was hit — it may be the daily limit that's too low, not the monthly. Also verify the budget type (tokens vs. cost). Some models use many tokens but are cheap per-token.

Budget not saving

Ensure all values are valid numbers. The API expects numeric values for all four fields. Zero means no limit. Check the console for error messages from the PUT request.

Alerts not appearing

Alerts are generated server-side when usage crosses thresholds. If no limits are configured, no alerts will be generated. Also check that the budget alerting system is enabled at the organization level.

Usage numbers seem wrong

Usage is aggregated server-side and may have a slight delay. Token counts include both input and output tokens. Cost calculations depend on the model's pricing. Refresh the page for the latest data.

Organization Context

When an agent belongs to a client organization, budget management integrates with org-level allocations:

Org Budget Allocation — An info banner shows "Budget limits follow [Org Name] allocation" along with the organization's budget cap if configured.
Budget Caps — Organizations can set overall budget caps that apply as an upper bound to all agents within the org. Individual agent limits cannot exceed the org cap.
Usage Tracking — Token and cost usage is tracked both at the agent level and aggregated at the organization level for billing and reporting.

What happens if the org budget cap is lower than the agent's limit?

The organization budget cap takes precedence. Even if an agent's individual limit is higher, the agent will be paused when the org-wide cap is reached.

Agent Activity Log Agent Workforce Agent Guardrails Agent Deployment

AgenticMail Enterprise Documentation Report an issue