> ## 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.

# Deprecation of Rate Limiting V1 — 2nd November, 2026

> Rate Limiting V1 (gateway-rate-limiting-config) is deprecated in favour of Rate Limiting V2 and will be removed on 15th December, 2026.

> [!WARNING]
>
> **Applicable to:** Tenant admins who have rate limit rules defined as `type: gateway-rate-limiting-config` (Rate Limiting V1). If you only use [Rate Limiting V2](https://www.truefoundry.com/docs/ai-gateway/ratelimiting-v2.md) (`tenant-rate-limit-config/model` or `tenant-rate-limit-config/mcp`), this change does not affect you.
>
> **Deprecation:** Rate Limiting V1 is **deprecated** and will be **fully removed on 15th December, 2026**. Existing V1 rules keep working until then. Recreate them in V2 before that date.

## What Is Changing

Rate Limiting V1, the single `gateway-rate-limiting-config` document holding an ordered `rules` list, is deprecated. [Rate Limiting V2](https://www.truefoundry.com/docs/ai-gateway/ratelimiting-v2.md) replaces it with one named limit per config.

Both systems currently run in parallel: V1 is checked first, and V2 is consulted only when no V1 rule blocks the request. Existing V1 rules continue to be enforced during the transition, but new rate limits should be created in V2.

## Why This Change

V1 enforced only the first matching rule in a list, so which limit applied to a request depended on rule order, and usage was still counted against every rule the request matched. This made limits hard to reason about and led to shared buckets being saturated by traffic that was never blocked by them.

V2 addresses these gaps:

* **Predictable evaluation**: every matching limit must allow a request, so limits compose without depending on order.
* **Richer limits**: several windows (requests and tokens, per minute, hour, and day) on one limit, `NOT IN` exclusions, provider account filters, and per-entity overrides.
* **Safe rollout**: `audit` and `soft_enforce` modes let you validate a limit before enforcing it.
* **MCP coverage**: rate limit `tools/call` requests through the MCP Gateway.

## What You Need to Do

**1. Audit your existing V1 rules**

List every rule in your `gateway-rate-limiting-config`: its `when` filters, `limit_to` and `unit`, and `rate_limit_applies_per`. Note which rules depended on ordering, where a specific rule was placed above a generic one.

**2. Recreate each rule in V2 in audit mode**

Go to **AI Gateway** → **Policies** → **Rate Limiting v2** and create an equivalent limit for each V1 rule, using **Apply as YAML** if you prefer to paste the config. Start with `mode: audit` to confirm the limit matches the traffic you expect. See the field mapping below.

**3. Account for the change in matching behavior**

In V1, only the first matching rule blocks a request. In V2, **every** matching limit is enforced. If a generic V1 rule sat below a specific one, narrow the V2 limit with `NOT IN` filters, or use [per-entity overrides](https://www.truefoundry.com/docs/ai-gateway/ratelimiting-v2.md), so the specific traffic is not capped twice.

**4. Switch to enforce, then delete the V1 rule**

Once a V2 limit behaves correctly in audit mode, set `mode: enforce` and delete the corresponding V1 rule. V2 counters start from zero and do not inherit V1 usage, and a request matching both a V1 rule and a V2 limit is counted and blockable by both until you remove the V1 rule.

## Field Mapping

| V1 (`gateway-rate-limiting-config`) | V2 (`tenant-rate-limit-config/model`) |
| - | - |
| `rules[].id` | Top-level `name`. Must be unique, so rules that share an `id` in V1 need distinct names |
| `when.subjects: ["user:alice@example.com"]` | `when.subjects.users.in: [alice@example.com]` |
| `when.subjects: ["team:backend"]` | `when.subjects.teams.in: [backend]` |
| `when.subjects: ["virtualaccount:ci-bot"]` | `when.subjects.virtual_accounts.in: [ci-bot]` |
| `when.models` | `when.models.in` |
| `when.metadata: {environment: production}` | `when.metadata.environment.in: [production]` |
| `limit_to` + `unit` | `limits.<unit>: <value>`. One limit can hold several units |
| `rate_limit_applies_per: ['user']` | `applies_to.type: per-user` |
| `rate_limit_applies_per: ['model']` | `applies_to.type: per-model` |
| `rate_limit_applies_per: ['virtualaccount']` | `applies_to.type: per-virtual-account` |
| `rate_limit_applies_per: ['metadata.project_id']` | `applies_to.type: metadata` with `applies_to.metadata: project_id` |
| Not supported | `mode`: `enforce`, `audit`, or `soft_enforce` |

> [!WARNING]
>
> V2 partitions a limit on **exactly one** dimension, fixed at creation. A V1 rule with two values in `rate_limit_applies_per`, such as `['user', 'model']`, has no direct V2 equivalent. Split it into separate limits, or choose the dimension that matters most, before the removal date.

## Example

A V1 rule that gives every user in the `backend` team 1,000,000 tokens per day on `gpt-4o` in production:

```yaml theme={"dark"}
name: ratelimiting-config
type: gateway-rate-limiting-config
rules:
  - id: per-user-gpt4o
    when:
      subjects: ["team:backend"]
      models: ["openai-main/gpt-4o"]
      metadata:
        environment: production
    limit_to: 1000000
    unit: tokens_per_day
    rate_limit_applies_per: ["user"]
```

The equivalent V2 limit, created in audit mode first:

```yaml theme={"dark"}
type: tenant-rate-limit-config/model
name: per-user-gpt4o
when:
  subjects:
    teams:
      in:
        - backend
  models:
    in:
      - openai-main/gpt-4o
  metadata:
    environment:
      in:
        - production
limits:
  tokens_per_day: 1000000
applies_to:
  type: per-user
mode: audit
```

For the full list of filters, windows, and overrides, see the [Rate Limiting V2 YAML reference](https://www.truefoundry.com/docs/ai-gateway/ratelimiting-v2.md#yaml-configuration-reference).

## Timeline

| Milestone | Date |
| - | - |
| Deprecation announcement | **2nd November, 2026** |
| Rate Limiting V1 (`gateway-rate-limiting-config`) fully removed | **15th December, 2026** |

> [!WARNING]
>
> Migrate to Rate Limiting V2 well ahead of **15th December, 2026**. Rate limits that exist only in V1 will stop being enforced after that date, which leaves the traffic they covered unthrottled.

## References

* [Rate Limiting (V2)](https://www.truefoundry.com/docs/ai-gateway/ratelimiting-v2.md)
* [Rate Limiting (V1)](https://www.truefoundry.com/docs/ai-gateway/ratelimiting.md)
* [Relationship to rate limiting V1](https://www.truefoundry.com/docs/ai-gateway/ratelimiting-v2.md#relationship-to-rate-limiting-v1)

***

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


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