> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Budgets

> Warn or block spending per organization, group, member, API key, agent, turn or end user.

[Budgets](https://platform.xpander.ai/governance/budgets) (**Platform > AI governance > Budgets**) caps spend on model calls. A call goes through only when every budget it belongs to has room left.

![Diagram](https://docs.xpander.ai/images/diagrams/run-llm-gateway-budgets-and-blocks-00781690.svg)

Limits are in credits when your organization is billed in credits (1 credit = \$0.01, with the dollar value shown), otherwise in USD. Periods are **Day**, **Week** (starting Monday) or **Month**. Calls on a person's own Claude plan, and work xpander does for you that Logs marks **Not billed**, count toward no budget.

## What each budget covers

| Budget | Where | Covers |
| - | - | - |
| **Organization limit** | **Organization limit** > **Set limit** (**Edit** once a limit is set) | Everything in a month: agent runs and people's coding tools together |
| **Groups** | **Spending limits by scope** > **Groups** | Coding tools and keys of every member whose primary group it is |
| **Members** | **Spending limits by scope** > **Members** | One person's coding tools, keys and the agent runs they start |
| **API keys** | **Spending limits by scope** > **API keys** | One key |
| **Agents** | **Spending limits by scope** > **Agents** | The default limit for each agent without a budget of its own. An agent's own budget is set in its settings, under **Advanced** > **Budget**; its row shows it as **In agent settings** |
| **End users** | **Spending limits by scope** > **End users** | One user of your own app, by the `user` field your app sends |
| **Per-agent budget** and **Per-turn budget** | The agent's settings, under **Advanced** > **Budget** | One agent, and one turn of it |

Budgets stack: a person's budget and their group's both apply. An agent's call counts for the agent, the turn and the person who started the run. Every call counts toward the organization limit.

## Set the organization limit

In **Overview**, on **Organization limit**, choose **Set limit** (**Edit** once a limit is set), enter **Limit per month** (empty for none) and choose **Save limit**. When it is reached, requests stop. **Overview** also counts budgets **over the limit**, **near the limit** (75-99%) and **under 75%**.

An account run by a main account shows an **Account limit** card. Only the main account's admins change it, and the account's own limit can only be lower.

## Add a budget

![Add a group budget form with Group, Limit in credits, Every, When reached (Block or Notify only) and Email admins at](https://mintcdn.com/xpanderai-099931d1/65C_XNxucwf3Ltb_/images/llm-gateway/09-budgets.png?fit=max\&auto=format\&n=65C_XNxucwf3Ltb_\&q=85\&s=9444926acb9e9ed2d866df5719bb76e7)

Adding a budget for a group: the limit, the period, what happens when it is reached, and when admins are emailed.

Under **Spending limits by scope**, pick a tab, choose **Add budget**, and pick who it is for (for an end user, the **End user ID** your app sends as `user`). Then set:

* **Limit** and **Every** (**Day**, **Week** or **Month**).
* **When reached**: **Block** stops calls until the period resets. **Notify only** lets usage continue.
* **Email admins at**: **50%**, **75%**, **80%**, **90%**, **100%**, once per period each.

Choose **Save budget**. A new budget starts as **Month**, **Notify only**, alerting at 50%, 75% and the full limit. Choose **Block** for a hard stop.

Each tab has a pinned **Default budget for ...** row that applies to everyone without their own budget. **Remove budget** sends a row back to the default.

## Rate limits

Alongside a budget, a rate limit caps **Requests/s**, **Tokens/s** (input and output together) and **At once** (calls in flight), over a rolling 60 seconds. The minimum is 1 request and 100 tokens a second, and an empty field means no limit. Open it with **Rate limit and budget** in a row's menu. Calls over the limit get `429` ([Errors](https://docs.xpander.ai/run/llm-gateway/errors.md)). If the menu shows only **Set budget**, rate limits are off for your organization: ask your xpander contact.

## Agent and turn budgets

These are set in each agent's settings, under **Advanced**. **Budget rules**, opened from the top of the Budgets page, holds what they share: **Maximum agent budget**, **Enforce agent, turn and member budgets** (off means track only, never block) and **Email alerts for agent, turn and member budgets**.

## What people see at a limit

| Where | What they see |
| - | - |
| **xpander Chat** | **Budget limit reached** (*Raise the budget or wait for the next period.*). A run that hits its budget mid-turn finishes the call in progress, then stops. |
| **Coding tool or SDK** | `429` with *The daily / weekly / monthly spending limit set for this ... on the xpander LLM Gateway is reached until ... Ask your admin to raise it, or wait.* At the organization limit, `402`. |
| **Logs** | **Budget reached**, with the blocking budget named in **Gateway decisions** |
| **Their own [Usage](https://chat.xpander.ai/?settings=my-usage)** | **Limit reached** and when calls resume. Members see *For a higher limit, ask an organization admin.* Admins get **Change limit**. |

**Notify only** never refuses a call.

## Self-hosted installs

Hybrid and Air-Gapped installs enforce agent, member and organization budgets for agents on the install, with their own counters. A block holds even when the install can't reach xpander cloud. Calls on your own keys count at the cost the gateway measures, matching Logs. Alert emails are sent from xpander cloud only.

* **Hybrid:** budgets are set in the Platform and reach your install within seconds. Your install reports its spend, so cloud totals include it. People's coding tools go through xpander cloud and are stopped there.
* **Air-Gapped:** budgets are set and enforced entirely inside your install.

## Next steps

> **[Fix a refused call](https://docs.xpander.ai/run/llm-gateway/errors.md)**
>
> What `429` and `402` mean.

> **[See what each request cost](https://docs.xpander.ai/run/llm-gateway/requests-and-costs.md)**
>
> Spend per request, person and agent.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.