Budget Management

What Is Budget Management?

Budget Management gives administrators precise control over how much each user, team, or the whole organization can spend on AI API calls per day and per month. When a limit is reached, AgentWatch automatically blocks further requests — preventing runaway bills from scripting errors, infinite loops, or unexpected usage spikes — and sends configurable alert notifications at configurable thresholds.

Budget Hierarchy

Limits cascade in three tiers. A lower tier inherits the tier above unless overridden:

Organization Default Budget
      └── Team Budget  (overrides org default for all team members)
              └── Individual User Budget  (overrides team default for one user)

Tier	Default Daily Limit	Default Monthly Limit	Where Configured
Organization	No hard cap (set by super admin)	No hard cap	Settings → General
Team	$50.00	$1,500.00	Management → Budget Management
User / Tenant	$10.00	$300.00	Management → Employee Management

A Budget Override can temporarily raise a single user or team’s limit (with an expiry date), useful for end-of-quarter bursts or short-term projects.

How Budget Enforcement Works

Every inbound API request passes through the budget gate before the LLM is called:

Inbound API Request
        │
        ▼
┌───────────────────────────────┐
│  Resolve effective budget:    │
│  User → Team → Org (cascade)  │
└────────────┬──────────────────┘
             │
             ▼
┌───────────────────────────────┐
│  Check Daily Limit            │──── Exceeded ──► 429 Budget Exceeded
└────────────┬──────────────────┘
             │ OK
             ▼
┌───────────────────────────────┐
│  Check Monthly Limit          │──── Exceeded ──► 429 Budget Exceeded
└────────────┬──────────────────┘
             │ OK
             ▼
       Forward to LLM
             │
             ▼
    Record token usage + cost
             │
             ▼
  Send threshold alerts if needed

Daily limits reset at midnight UTC. Monthly limits reset on the 1st of each calendar month.

Budget Status Fields

AgentWatch tracks the following per tenant/user in real time:

Field	Description
dailySpent	Cost consumed today (USD)
monthlySpent	Cost consumed this month (USD)
dailyBudget	Daily limit in effect
monthlyBudget	Monthly limit in effect
dailyRemaining	How much budget is left today
budgetOverride	Temporary raised limit (if set)
overrideExpiry	When the override expires
warningLevel	none / warning / critical / blocked

Alert Thresholds

Threshold	Default	Alert Type
80% of daily or monthly	Configurable	First warning notification
90% of daily or monthly	Fixed	Second warning (high alert)
100%	Fixed	Budget exceeded — requests blocked

Alerts are sent via:

• Email — to configured recipients (Settings → General → Notifications)
• Webhook — HTTP POST to your configured webhook URL with a signed payload:

{
  "event": "budget.alert",
  "level": "warning",
  "tenantId": "emp-001",
  "tenantName": "Jane Smith",
  "budgetType": "daily",
  "budgetLimit": 10.00,
  "currentSpend": 8.12,
  "percentUsed": 81.2,
  "threshold": 80,
  "timestamp": "2026-05-06T14:22:00Z"
}

Webhook requests are signed with HMAC-SHA256 via the X-AgentOneHub-Signature header using the WEBHOOK_SECRET environment variable.

Budget Enforcement for Web Chat

Web chat traffic (ChatGPT, Claude.ai, Gemini, etc.) routed through AgentWatch Connect is subject to the same per-user daily and monthly limits as direct API calls.

1. Before forwarding a web chat request to the upstream site, the agent calls the budget check endpoint.
2. If the user’s budget is exceeded, the request is blocked:

HTTP 403 Forbidden
Budget exceeded: You have reached your daily limit of $10.00 for web chat usage.
Contact your administrator to request an increase.

3. After the request completes, a post-request notification fires to update alert tracking.

Step-by-Step: Setting a Team Budget

1. Navigate to Management → Budget Management.
2. Select the Team from the list, or click Create Team if one doesn’t exist.
3. Enter a Daily Limit and Monthly Limit in USD.
4. Set the Warning Threshold (default 80%) — alerts fire when spending crosses this percentage.
5. (Optional) Enable email or webhook notifications under Settings → General → Notifications.
6. Click Save. The new limits take effect immediately.

Step-by-Step: Setting an Individual Budget Override

1. Navigate to Management → Employee Management.
2. Find the user and click Edit.
3. Under Budget, enter the new temporary daily or monthly limit.
4. Set an Override Expiry date — the limit reverts to the team default after this date.
5. Click Save.

API Reference

Method	Endpoint	Description
GET	/api/admin/budgets	List all team/user budgets
PUT	/api/admin/budgets/:tenantId	Update a tenant’s budget limits
GET	/api/my/budget	Get the current user’s budget status
POST	/api/admin/budgets/:tenantId/override	Set a temporary budget override