# AI Gateway Budget Alerts

> **Scope of this page**
>
> This page documents the Zuplo **gateway** runtime (API, AI, and MCP gateways), not the Developer Portal.
>
> It applies to every Zuplo hosting option: Managed Edge, Managed Dedicated, and Self-Hosted. See [Hosting options](https://zuplo.com/docs/articles/hosting-options).

Budget alerts tell you when usage crosses an amount set in a budget rule, so you
don't have to watch the analytics to find out. There's nothing to set up. Each
**Warn** or **Block** row in a [budget rule](./usage-limits.mdx) sets an amount;
crossing that amount sends an alert to the people who can see the pool or app.

## What you're notified about

A budget rule caps cost, tokens, or requests over a UTC period and can have a
**Warn** row, a **Block** row, or both for the same meter and period. See
[Usage Limits](./usage-limits.mdx) for how to write one.

Each budget is reported once per row per period: the first time its usage
crosses the amount, and again after the period resets. A **By metadata** rule
gives every value its own budget, so each value is reported separately. Usage is
checked about once a minute, and an alert usually arrives within a minute or two
of the crossing. Alerts for several values of one rule are held for up to five
minutes so they arrive together.

| Alert             | When it's sent                           | What it means                                                                                                                                                                                                                                         |
| ----------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Warning**       | Usage first crosses the **Warn** amount  | Requests continue. Use the time left in the period to raise the limit or slow the caller down.                                                                                                                                                        |
| **Limit reached** | Usage first crosses the **Block** amount | Requests are rejected with `429 Too Many Requests`, or served by the app's [quota fallback](./fallback.mdx), until the period resets. The alert includes the reset time. See [When a limit is exceeded](./usage-limits.mdx#when-a-limit-is-exceeded). |

If one request pushes usage past both amounts, you get only a **Limit reached**
alert.

What the alert names depends on the rule's scope:

- A **Shared** rule names the gateway, pool, or app whose budget it is.
- A **By metadata** rule names the metadata value that crossed, such as one
  `x-user` value. When several values of the same rule cross an amount within
  five minutes, they arrive as one alert listing the values.
- The [User App](./user-apps.mdx)'s per-person budget names the person.

## Who is notified

Alerts go to the people who can already see the usage in the Zuplo Portal:

- **A pool or an app**: everyone with view access to it. A pool member receives
  alerts for that pool and the apps in it; someone with access to the whole
  project receives alerts for every pool.
- **The User App**: only the Admins who can edit it, the people who set its
  budget. Everyone else on the project can see only their own usage, so they
  aren't told about the app's total or about other people.
- **A personal budget**: the person it belongs to, and the User App's Admins.

## Where alerts arrive

Each alert is delivered two ways, and both are on by default:

- **In-app feed**: the notification bell in the Zuplo Portal header. The feed
  links to the app, pool, or gateway page that shows the usage.
- **Email**: a message to the address on your Zuplo profile.

## Turn alerts off

Turning alerts off changes only what you receive. Everyone else keeps their own
settings.

### Turn off all budget alerts

To stop receiving budget alerts for every gateway, open your
[Profile](https://portal.zuplo.com/user/profile) in the Zuplo Portal and find
the **Notifications** section. On the **AI Gateway Budget Alerts** row, clear
**In-app Feed**, **Email**, or both.

### Mute a gateway, pool, or app

To keep alerts for most of a gateway and silence the parts you don't need, mute
them from the analytics:

<Stepper>

1. Open your AI Gateway project in the Zuplo Portal and go to
   [**Observability → Analytics**](https://portal.zuplo.com/+/account/project/ai/analytics),
   then select **Pools & Apps**.

1. Select the alert bell on a pool card or an app row. It's the mute control for
   that pool or app.

1. Switch off **Warnings**, **Limit reached**, or both.

</Stepper>

Muting a pool mutes every pool and app inside it, including ones created later.
Under a muted pool, each pool and app shows locked switches and names the muted
pool. To receive alerts for any of them again, turn that pool's alerts back on.

The gateway card at the top of the **Pools & Apps** page covers the whole
gateway. Muting it mutes every pool, every app, the User App, and every person's
personal budget, your own included.

:::note{title="Alerts don't change enforcement"}

Muting an alert, or turning the category off on your profile, changes who is
told, not what happens. A **Block** row still rejects requests at its amount, or
sends them to the app's [quota fallback](./fallback.mdx), and a **Warn** row
still lets them through.

:::

## Related resources

- [Usage Limits](./usage-limits.mdx) - Set the amounts that trigger these
  alerts.
- [User Apps](./user-apps.mdx) - Set the per-person budget behind personal
  budget alerts.
- [Fallback Models](./fallback.mdx) - Serve a cheaper model instead of a `429`
  when a **Block** amount is reached.