---
title: Budgets
seoTitle: "Langfuse AI Gateway budgets: spend limits per key, user, and organization (beta)"
description: Set budgets that cap what each gateway key, each user, and the whole organization can spend on the Langfuse AI Gateway. The gateway rejects requests once a budget is reached.
---

# Budgets

  **Beta.** The Langfuse AI Gateway is in public beta and can still change.

Budgets are spend limits: they cap what gateway traffic may cost in USD. Once a budget is reached, the gateway rejects new requests until the budget resets. Requests that are already in flight still complete.

You manage budgets under **AI Gateway → Budgets**.

  ![Budgets page with the organization budget, spend over time, and a table of gateway keys with their spend against each budget](/images/docs/ai-gateway/budgets.png)

## Budget types [#budget-types]

| Budget                               | Caps                                    | Who can set it                                    |
| ------------------------------------ | --------------------------------------- | ------------------------------------------------- |
| API key                              | One gateway key                         | Admins and owners, and any user on their own keys |
| User                                 | All gateway keys of one user            | Admins and owners                                 |
| [Default](#default-budgets)          | Each key or user without its own budget | Admins and owners                                 |
| [Organization](#organization-budget) | All gateway spend of the organization   | Admins and owners                                 |

A request counts against every budget that applies to it: its key's budget, the key owner's user budget, and the organization budget. Whichever is reached first blocks the request.

## Set a budget [#set-a-budget]

Select **Add budget**, or **Edit budget** on a row in the **Users** or **API keys** table. You can also set a budget when you [create a key](/docs/gateway/features/api-keys#create-a-key).

A budget resets daily (00:00 UTC), weekly (Monday), monthly (on the 1st), or never. It counts spend from when you set it. Changing the amount keeps the spend counted so far; changing the reset interval starts counting again.

  Spend is calculated from model prices, so a key with a budget can only call
  models that Langfuse has a [price](/docs/observability/features/token-and-cost-tracking)
  for.

## Default budgets [#default-budgets]

A default budget applies to every key, or every user, that has no budget of its own, including service account keys. Each key or user counts its own spend against the default; they don't share it. Admins and owners set one default for keys and one for users, from the **API keys** and **Users** tables.

A key's or user's own budget replaces the default. Removing it puts the key or user back on the default.

## Organization budget [#organization-budget]

The organization budget caps the total gateway spend of the organization, across all users and keys. An organization has one organization budget. Admins and owners set it on the Budgets page, which also shows its current spend.

## When a budget is reached [#budget-reached]

The gateway responds with `429` and the error code `spend_limit_exceeded`, and the message names the budget, for example: `This key's user has spent $12.00 of its $10.00 monthly budget.` See [AI Gateway errors](/faq/all/ai-gateway-error-codes) for the full list of error codes.

When a key or user budget is reached, the key owner or user and the organization's owners get an email.

<!-- agent-instructions -->

---

## Agent Instructions

This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/docs/gateway/features/budgets.md`.

### Querying these docs

If the answer is not on this page, query the documentation instead of guessing:

- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:

  ```bash
  curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
  ```

- **Index of every page**: <https://langfuse.com/llms.txt>, with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).

### Before writing Langfuse code

- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx @langfuse/cli api <resource> <action>`) to read or write traces, prompts, datasets, and scores from the terminal.

Found an error in these docs? Please open an issue at <https://github.com/langfuse/langfuse-docs/issues>.
