# How to Configure Budget Limits and Spend Alerts in LiteLLM

> Configure budget limits and spend alerts in LiteLLM with its three-layer system. Set caps, get Slack/email alerts, and enforce limits per model, team, or user. Optimize your LLM spending effectively.

- Repository: [Berri AI/litellm](https://github.com/BerriAI/litellm)
- Tags: how-to-guide
- Published: 2026-03-26

---

**LiteLLM provides a three-layer budget management system that lets you set spending caps, receive alerts via Slack or email, and enforce limits per-model, per-team, or per-user by combining the budget manager, limit enforcement hooks, and alert dispatchers.**

The BerriAI/litellm repository includes a comprehensive **budget manager** designed to prevent runaway costs across OpenAI, Azure, Anthropic, and other LLM providers. Whether you need to cap spending by user session, team, or specific model, LiteLLM’s proxy server can block requests that exceed financial thresholds and notify stakeholders through configurable alert channels.

## How the Budget System Works

LiteLLM implements spending controls through three coordinated layers:

- **Budget Store** – Persists budget definitions in the proxy database via [`litellm/budget_manager.py`](https://github.com/BerriAI/litellm/blob/main/litellm/budget_manager.py), storing `max_budget`, `soft_budget`, and duration intervals.
- **Limit Enforcement** – Intercepts each request using [`litellm/router_strategy/budget_limiter.py`](https://github.com/BerriAI/litellm/blob/main/litellm/router_strategy/budget_limiter.py) and specialized hook modules ([`max_budget_limiter.py`](https://github.com/BerriAI/litellm/blob/main/max_budget_limiter.py), [`max_budget_per_session_limiter.py`](https://github.com/BerriAI/litellm/blob/main/max_budget_per_session_limiter.py), [`model_max_budget_limiter.py`](https://github.com/BerriAI/litellm/blob/main/model_max_budget_limiter.py)) to approve or deny calls.
- **Alerting** – Dispatches notifications through [`litellm/integrations/SlackAlerting/budget_alert_types.py`](https://github.com/BerriAI/litellm/blob/main/litellm/integrations/SlackAlerting/budget_alert_types.py) when spending crosses warning thresholds.

When a request hits the proxy, the system executes a four-step sequence: **Lookup** (resolve the budget scope from [`budget_management_endpoints.py`](https://github.com/BerriAI/litellm/blob/main/budget_management_endpoints.py)), **Check** (compare current spend against limits), **Allow/Block** (return HTTP 429 if over budget), and **Update** (record the actual cost after successful LLM calls).

## Configure Budget Limits via the Management API

### Define Spending Caps and Warning Thresholds

Create budgets programmatically by posting to the budget management endpoint defined in [`litellm/proxy/management_endpoints/budget_management_endpoints.py`](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/management_endpoints/budget_management_endpoints.py):

```bash
curl -X POST https://<proxy-host>/budget \
  -H "Authorization: Bearer <admin-key>" \
  -H "Content-Type: application/json" \
  -d '{
        "budget_name": "team_alpha_budget",
        "budget_type": "team",
        "identifier": "team_alpha",
        "max_budget": 500.0,
        "soft_budget": 400.0,
        "duration": "monthly",
        "alert_channels": ["slack", "email"]
      }'

```

Valid `budget_type` values include `team`, `organization`, `user`, `tag`, and `model`. The `max_budget` acts as a hard ceiling that blocks requests, while `soft_budget` triggers alerts without interrupting service.

### Set Alert Channels and Notification Preferences

The `alert_channels` array maps to dispatchers in [`budget_alert_types.py`](https://github.com/BerriAI/litellm/blob/main/budget_alert_types.py). Supported channels include **Slack webhooks**, **SMTP email**, and **custom webhooks**. To add custom notification services, extend the `ALERT_DISPATCHERS` dictionary in the [`budget_alert_types.py`](https://github.com/BerriAI/litellm/blob/main/budget_alert_types.py) module.

## Enforce Budget Limits Programmatically

Use the Python SDK to set per-user budgets and per-session caps for granular control over individual request costs:

```python
import litellm

# Create a per-user monthly budget (soft $20, hard $30)

litellm.set_budget(
    budget_type="user",
    identifier="user_12345",
    max_budget=30.0,
    soft_budget=20.0,
    duration="monthly",
    alert_channels=["slack"]
)

# Enforce a per-session limit of $5

litellm.set_session_budget(
    user_id="user_12345",
    session_max_budget=5.0
)

# Requests exceeding the session budget are rejected automatically

response = litellm.completion(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Explain quantum entanglement"}]
)

```

The session-level enforcement logic resides in [`litellm/proxy/hooks/max_budget_per_session_limiter.py`](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/hooks/max_budget_per_session_limiter.py), which checks the running total for each conversation thread before allowing the request to proceed.

## Configure Global Budget Defaults

Set organization-wide fallback values using environment variables that [`budget_manager.py`](https://github.com/BerriAI/litellm/blob/main/budget_manager.py) reads at startup:

| Variable | Purpose |
|----------|---------|
| `MAX_GLOBAL_BUDGET` | Hard ceiling applied when no explicit budget is defined for a scope. |
| `SOFT_GLOBAL_BUDGET` | Warning threshold used for implicit budgets. |
| `BUDGET_RESET_CRON` | Cron expression defining when usage counters reset (e.g., daily). |

These defaults ensure that unconfigured teams or users still operate under spending guardrails.

## Manage Budgets in the LiteLLM Dashboard

The React-based administrative interface provides visual controls for non-technical stakeholders:

- **Budget Panel** ([`ui/litellm-dashboard/src/components/budgets/budget_panel.tsx`](https://github.com/BerriAI/litellm/blob/main/ui/litellm-dashboard/src/components/budgets/budget_panel.tsx)) – Displays current spend, remaining allowance, and alert status for all configured budgets.
- **Edit Budget Modal** ([`budget_modal.tsx`](https://github.com/BerriAI/litellm/blob/main/budget_modal.tsx) and [`edit_budget_modal.tsx`](https://github.com/BerriAI/litellm/blob/main/edit_budget_modal.tsx)) – Allows admins to adjust `max_budget`, `soft_budget`, and alert channels through a web form.
- **Alert History** – Tracks dispatched notifications and their delivery status.

## Key Implementation Files

Understanding the source architecture helps when debugging limit violations or extending functionality:

| File | Role |
|------|------|
| [`litellm/budget_manager.py`](https://github.com/BerriAI/litellm/blob/main/litellm/budget_manager.py) | Central persistence and spend aggregation |
| [`litellm/router_strategy/budget_limiter.py`](https://github.com/BerriAI/litellm/blob/main/litellm/router_strategy/budget_limiter.py) | Core request-level checks and throttling logic |
| [`litellm/proxy/hooks/max_budget_limiter.py`](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/hooks/max_budget_limiter.py) | Global hard-budget enforcement |
| [`litellm/proxy/hooks/max_budget_per_session_limiter.py`](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/hooks/max_budget_per_session_limiter.py) | Session-scoped spending caps |
| [`litellm/proxy/hooks/model_max_budget_limiter.py`](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/hooks/model_max_budget_limiter.py) | Model-specific budget overrides |
| [`litellm/integrations/SlackAlerting/budget_alert_types.py`](https://github.com/BerriAI/litellm/blob/main/litellm/integrations/SlackAlerting/budget_alert_types.py) | Alert channel dispatch mapping |
| [`litellm/proxy/management_endpoints/budget_management_endpoints.py`](https://github.com/BerriAI/litellm/blob/main/litellm/proxy/management_endpoints/budget_management_endpoints.py) | REST API for CRUD operations |

## Summary

- **Configure budget limits and spend alerts in LiteLLM** using either the REST API (`/budget` endpoint), Python SDK (`set_budget()`), or React dashboard.
- The system distinguishes between **hard limits** (`max_budget`) that return HTTP 429 errors and **soft limits** (`soft_budget`) that trigger Slack/email notifications.
- Enforcement occurs through specialized hooks including [`max_budget_limiter.py`](https://github.com/BerriAI/litellm/blob/main/max_budget_limiter.py) and [`max_budget_per_session_limiter.py`](https://github.com/BerriAI/litellm/blob/main/max_budget_per_session_limiter.py).
- Global defaults via environment variables provide fallback protection for unconfigured scopes.

## Frequently Asked Questions

### What happens when a LiteLLM budget limit is exceeded?

When a request would exceed the `max_budget`, the proxy returns an **HTTP 429 error** and blocks the LLM call. If the request crosses only the `soft_budget` but remains under the hard limit, it proceeds while the system queues an alert notification to the configured channels.

### Can I set temporary budget increases for specific teams?

Yes. According to the [`temporary_budget_increase.md`](https://github.com/BerriAI/litellm/blob/main/temporary_budget_increase.md) documentation, administrators can issue temporary budget overrides for specific time windows. This is useful for handling traffic spikes or special projects without permanently increasing baseline spending caps.

### Which alert channels does LiteLLM support for budget notifications?

LiteLLM supports **Slack webhooks**, **SMTP email**, and **custom webhooks** out of the box. The mapping between channel names and sender implementations lives in [`budget_alert_types.py`](https://github.com/BerriAI/litellm/blob/main/budget_alert_types.py), where you can extend the `ALERT_DISPATCHERS` dictionary to integrate with PagerDuty, Microsoft Teams, or internal incident management systems.

### How do per-session budgets differ from per-user budgets?

**Per-user budgets** track cumulative spending across all sessions for that identifier over a defined duration (daily, weekly, monthly). **Per-session budgets**, enforced by [`max_budget_per_session_limiter.py`](https://github.com/BerriAI/litellm/blob/main/max_budget_per_session_limiter.py), apply only to a single conversation thread or request sequence, preventing individual long-running chats from consuming the entire monthly allocation.