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

# Configure AI Budget Alerts and Hard Caps in Tokonomics

> Configure Tokonomics to send Slack, Teams, email, or webhook alerts when your AI spend crosses 50%, 80%, or 100% of your monthly budget.

Tokonomics tracks your cumulative AI spend in real time and fires alerts the moment you cross a threshold you define. You set a monthly budget, choose which percentages trigger a notification, and configure where those notifications go — Slack, Teams, email, or any HTTPS webhook endpoint. No polling, no manual checks, no surprise invoices.

<Steps>
  <Step title="Set a monthly budget">
    Navigate to **Dashboard → Settings → Budget** and enter your monthly cap in USD. Tokonomics uses this figure as the baseline for all threshold calculations. You can update it at any time; changes take effect immediately.
  </Step>

  <Step title="Choose alert thresholds">
    Select which spend percentages should trigger an alert. The available thresholds are **50%**, **80%**, and **100%**. You can enable any combination — for example, enable 80% and 100% if you only want a warning near the limit and a final alert when you hit it. Each threshold can route to its own channel.
  </Step>

  <Step title="Configure alert channels">
    Choose where each alert is delivered.

    <Tabs>
      <Tab title="Slack">
        Paste your Slack incoming webhook URL into the **Slack webhook URL** field. Tokonomics sends a formatted message that includes the threshold, current spend, and budget total.

        ```text theme={null}
        https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
        ```
      </Tab>

      <Tab title="Teams">
        Paste your Microsoft Teams incoming webhook URL into the **Teams webhook URL** field.

        ```text theme={null}
        https://your-org.webhook.office.com/webhookb2/...
        ```
      </Tab>

      <Tab title="Email">
        Enter one or more email addresses. Tokonomics sends a plain-text alert email from `alerts@tokonomics.ca` when the threshold is crossed.
      </Tab>

      <Tab title="Webhook">
        Enter any HTTPS URL. Tokonomics sends a `POST` request with a JSON payload to that URL when the threshold is crossed. See **Webhook payload** below for the exact schema.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Test the alert">
    Click **Send test** next to any configured channel in the dashboard. Tokonomics immediately delivers a sample payload so you can confirm the integration is working before you hit a real threshold.
  </Step>
</Steps>

## Webhook payload

When a threshold is crossed, Tokonomics `POST`s the following JSON body to your webhook URL:

```json theme={null}
{
  "event": "budget.threshold",
  "threshold_percent": 80,
  "current_spend": 40.00,
  "monthly_budget": 50.00,
  "budget_used_percent": 80.0
}
```

| Field                 | Type   | Description                                                    |
| --------------------- | ------ | -------------------------------------------------------------- |
| `event`               | string | Always `budget.threshold`                                      |
| `threshold_percent`   | number | The threshold that was crossed (50, 80, or 100)                |
| `current_spend`       | number | Your cumulative spend in USD at the time of the alert          |
| `monthly_budget`      | number | Your configured monthly cap in USD                             |
| `budget_used_percent` | number | Exact percentage used, which may exceed the threshold slightly |

## Hard caps (Pro)

Pro plan users can enable a **hard cap** in addition to alerts. When your spend reaches 100% of your monthly budget and the hard cap is active, Tokonomics rejects further requests with a `429 Too Many Requests` response until the budget resets or you increase your cap. This prevents runaway spend caused by loops or unexpected traffic spikes.

<Warning>
  Hard caps block all proxied requests once the budget is exhausted — including production traffic. Test your alerting and response handling at the 80% threshold before enabling this feature.
</Warning>

<Note>
  Alert delivery is best-effort. Tokonomics retries failed deliveries up to 3 times with exponential backoff before marking the alert as undelivered. You can see the delivery status of every alert in **Dashboard → Settings → Alert History**.
</Note>

For more detail on how budgets are calculated and reset, see [Budgets](/concepts/budgets).