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

# Usage alerts

> Usage alerts allow you to monitor your subscriptions' usage and billing by firing notifications when certain conditions are met.

## Overview

Usage alerts notify you when a subscription's usage crosses thresholds you define. Common use cases:

1. Allow customers to set and manage their own usage limits and budgets, empowering them to control their consumption;
2. Alert customers with skyrocketing usage to prevent unexpected costs or overages on their bills; or
3. Implement entitlement logic to halt usage tracking when a customer reaches their predefined limit, ensuring accurate billing and compliance.

## Create an alert

<Tabs>
  <Tab title="Dashboard">
    An alert must be tied to a specific subscription. To create an alert for a particular subscription, follow these steps:

    1. Access the specific subscription view;
    2. Click on the **Alerts** tab;
    3. Click on the **Add an alert** button;
    4. Select the type of alert (e.g., Lifetime Usage Amount);
    5. Set the progressive thresholds and code for the alert;
    6. Define the optional recurring threshold for the alert; and
    7. Click on the **"Create alert"** button to confirm.

    <Info>
      The alert threshold `code` helps distinguish between different types of alert notifications. For example, some notifications may indicate a `soft` limit, while others may trigger a `hard` limit, each with different levels of urgency or action required.
    </Info>

    <Frame caption="Create an alert">
      <img src="https://mintcdn.com/lago/L7Dc2Fm9iHz3bRSl/guide/images/create-alerts.png?fit=max&auto=format&n=L7Dc2Fm9iHz3bRSl&q=85&s=ee96470a6aab429b712ede6583be0009" width="2366" height="1944" data-path="guide/images/create-alerts.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Lifetime usage amount alert creation theme={"dark"}
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/subscriptions/:external_id/alerts" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
              "alert": {
                  "alert_type": "lifetime_usage_amount",
                  "code": "lifetime_usage_alerts",
                  "name": "Lifetime Usage Alerts",
                  "thresholds": [
                      {
                          "code": "soft",
                          "value": "1000.0",
                          "recurring": false
                      },
                      {
                          "code": "soft",
                          "value": "2000.0",
                          "recurring": false
                      },
                      {
                          "code": "hard",
                          "value": "15000.0",
                          "recurring": false
                      }
                  ],
                  "billable_metric_code": null
              }
          }'
      ```

      ```bash Billable metric usage alert creation theme={"dark"}
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/subscriptions/:external_id/alerts" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
              "alert": {
                  "alert_type": "billable_metric_current_usage_units",
                  "code": "api_calls_soft_limit",
                  "name": "API calls limit",
                  "billable_metric_code": "api_calls",
                  "thresholds": [
                      {
                          "code": "warn",
                          "value": "5000",
                          "recurring": false
                      },
                      {
                          "code": "repeat",
                          "value": "1000",
                          "recurring": true
                      }
                  ]
              }
          }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Alert types

Lago supports the following usage alert types:

* **Lifetime Usage Amount** (`lifetime_usage_amount`): Triggered when a subscription's lifetime usage exceeds predefined thresholds.
* **Current Usage Amount** (`current_usage_amount`): Triggered when a subscription's usage exceeds predefined thresholds for the current billing period.
* **Billable Metric Current Usage Amount** (`billable_metric_current_usage_amount`): Triggered when the usage of a specific billable metric exceeds predefined thresholds for the current billing period.
* **Billable Metric Current Usage Units** (`billable_metric_current_usage_units`): Triggered when the number of units of a specific billable metric exceeds predefined thresholds for the current billing period.

## Alert notifications

After configuring an alert and starting to ingest usage, you can listen for the `alert.triggered` webhook message. These webhooks serve as notifications sent to your system, indicating when an alert threshold has been crossed, along with all the relevant alert details.

```json theme={"dark"}
{
  "webhook_type": "alert.triggered",
  "object_type": "triggered_alert",
  "triggered_alert": {
    "lago_id": "ff604dc4-2223-412a-a8f4-8fde7dfd3346",
    "lago_alert_id": "98d00d14-dc17-40c8-81c2-701b7cdbb038",
    "lago_subscription_id": "0705ad6b-c063-421a-87b6-a6c25f98c842",
    "billable_metric_code": null,
    "alert_name": "Total Usage Alerts",
    "alert_code": "total_usage",
    "alert_type": "current_usage_amount",
    "current_value": "100.0",
    "previous_value": "0.0",
    "crossed_thresholds": [
      {
        "code": "hard_limit",
        "value": "100.0",
        "recurring": false
      }
    ],
    "triggered_at": "2025-05-27T19:25:02Z"
  }
}
```

## Limitations

* Alerts only evaluate usage data reported after their creation;
* Alerts are processed close to real time; and
* Each alert `code` must be unique per subscription, and only one alert per type (per billable metric for metric-scoped types) can exist on a subscription.