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

# Budgets and Rate Limits

> Spend caps and per-minute limits on keys and teams.

[Keys](https://developers.telnyx.com/docs/agent-gateway/authentication/keys.md) and [teams](https://developers.telnyx.com/docs/agent-gateway/authorization/allow-lists.md#teams) carry a budget and rate limits:

| Field | On | What It Limits |
| - | - | - |
| `max_budget` | Keys, teams | What the key or team may spend, in USD, until the budget resets. |
| `budget_resets_every` | Keys, teams | How often spend resets, as a number and a unit (`s`, `m`, `h`, or `d`), such as `30d`. |
| `requests_per_minute` | Keys, teams | Requests per minute. |
| `tokens_per_minute` | Keys, teams | Tokens per minute. |
| `max_parallel_requests` | Keys | Requests in flight at once. |

The instance applies the stricter of a key's limit and its team's, and refuses a model request past either. A request past a budget gets `422` with the error type `budget_exceeded`. A request past a rate limit gets `429` with a `retry-after` header, in seconds. `GET {gateway_url}/v1/models` does not count toward the limits.

A request's spend and tokens count when it completes, so the request that crosses a budget completes and the next one is refused. A request whose prompt and `max_tokens` would exceed the tokens left in the minute is refused before it runs.

Budgets enforce on instances created since 2026-10-29. Instances created before that date price every request at `0`, so spend never reaches a budget and no request is refused for one (AIPLAT-1630).

## New Limits

Limits go in the body of [`POST /v2/agent_gateways/{id}/teams`](https://developers.telnyx.com/api-reference/agent-gateway-teams/create-a-team) or [`POST /v2/agent_gateways/{id}/keys`](https://developers.telnyx.com/api-reference/agent-gateway-keys/create-a-key):

```json theme={null}
{
  "name": "support",
  "max_budget": 50,
  "budget_resets_every": "30d",
  "requests_per_minute": 120
}
```

A key's or team's `spend` and `budget_resets_at` show where it stands.

## Limit Changes

[`PATCH /v2/agent_gateways/{id}/keys/{key_id}`](https://developers.telnyx.com/api-reference/agent-gateway-keys/update-a-key) and [`PATCH /v2/agent_gateways/{id}/teams/{team_id}`](https://developers.telnyx.com/api-reference/agent-gateway-teams/update-a-team) change limits without reissuing anything. A field left out stays as it is, and `null` removes a limit.

```json theme={null}
{
  "max_budget": 100
}
```