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

# Budget Limiting V2 — v0.158.0

> Budget Limiting V2 introduces independent rules, tenant- and team-scoped budgets, multi-period and lifetime limits, and per-entity overrides in v0.158.0.

<Warning>
  **Applicable to:** Tenant admins and team managers who configure spending limits in **AI Gateway → Policies → Budget Limiting**. Existing Budget Limiting (V1) rules continue to work after upgrading to v0.158.0 — no immediate action is required.
</Warning>

## What Is Changing

Starting in **v0.158.0**, TrueFoundry AI Gateway introduces **Budget Limiting V2**, available at **AI Gateway → Policies → Budget Limiting v2**. V2 replaces the ordered-rule model in the current Budget Limiting page with independent rules and adds several capabilities:

* **Independent rules.** Every matching rule is evaluated and the request is blocked if any rule it touches is breached. There is no rule ordering or first-match precedence.
* **Tenant and team scopes.** Tenant budgets are managed by tenant admins and apply across the tenant. Team budgets can also be managed by team managers and apply to a single team.
* **Multiple periods per rule.** A single rule can enforce daily, weekly, monthly, quarterly, and lifetime limits at once.
* **Lifetime budgets.** A new "resets never" period lets you set a lifetime spend cap that never resets.
* **Per-entity overrides.** For per-user, per-model, per-virtual-account, or per-metadata rules, you can override the base limits for specific entities.
* **Per-user alert emails.** Email alerts on per-user budgets can notify the user who crossed the threshold using the `{{user.email}}` placeholder.

Both Budget Limiting V1 and V2 will run in parallel during the transition. We recommend creating all new rules in V2.

## Why This Change

Budget Limiting V1 evaluated an ordered list of rules where the first matching rule controlled allow/block. This made it hard to reason about which limit applied when a request matched several rules, and it did not support team-scoped administration, multiple periods per rule, lifetime budgets, or per-entity overrides.

Budget Limiting V2 addresses these gaps:

* **Predictable evaluation** — every matching rule must allow a request, so limits compose without depending on order.
* **Delegated administration** — team managers can manage their own team's budgets without tenant-admin access.
* **Richer limits** — multiple periods, lifetime caps, and per-entity overrides on a single rule.

## What You Need to Do

<Steps>
  <Step title="Start creating new rules in V2">
    Go to **AI Gateway → Policies → Budget Limiting v2** and create new budget rules there. See [Budget Limiting](/docs/ai-gateway/budget-limiting-v2) for the full configuration guide.
  </Step>

  <Step title="Audit your existing V1 rules">
    Review each V1 rule and note its filters, limits, and whether it acted as an override or a default. In V2, rules that previously relied on ordering will all apply together.
  </Step>

  <Step title="Recreate rules in V2">
    Create equivalent rules in V2. Use warn-only mode first if you want to validate spend patterns before enforcing. The [migration guide](/docs/ai-gateway/budgetlimiting#migrating-to-budget-limiting-v2) maps each V1 field to its V2 equivalent.
  </Step>

  <Step title="Disable V1 rules">
    Once V2 rules are enforcing correctly, disable the corresponding V1 rules. Both systems run in parallel during the transition, so disable V1 rules only after confirming V2 coverage.
  </Step>
</Steps>

## Timeline

| Milestone                        | Date                                                                                     |
| -------------------------------- | ---------------------------------------------------------------------------------------- |
| Budget Limiting V2 introduced    | v0.158.0                                                                                 |
| Budget Limiting V1 fully removed | **3 months after v0.158.0, or once all customers have migrated — whichever comes first** |

<Warning>
  We strongly encourage migrating to Budget Limiting V2 well ahead of the removal date to avoid disruptions to your spending controls.
</Warning>

## References

* [Budget Limiting (V2)](/docs/ai-gateway/budget-limiting-v2)
* [Budget Limiting (V1)](/docs/ai-gateway/budgetlimiting)
* [Migrating to Budget Limiting V2](/docs/ai-gateway/budgetlimiting#migrating-to-budget-limiting-v2)

***

If you have questions about the migration or run into anything unexpected, reach out to [**support@truefoundry.com**](mailto:support@truefoundry.com) — we're happy to help.