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

# Usage Alerts

> Set up threshold-based alerts on usage metrics, costs, and wallet balances.

Usage alerts let you define thresholds on usage metrics, costs, or wallet balances and receive notifications when those thresholds are crossed. They help you stay informed about customer activity without polling the API.

## Alert Types

Monigo supports three alert types, each monitoring a different dimension of customer activity.

### Usage Exceeded

Fires when a customer's metered usage on a specific metric crosses a threshold. Useful for notifying customers approaching their plan limits.

```bash theme={null}
curl -X POST https://api.monigo.co/api/v1/alerts?org_id=YOUR_ORG_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "usage_exceeded",
    "scope": "plan",
    "scope_id": "PLAN_ID",
    "metric_id": "METRIC_ID",
    "thresholds": [
      { "value": "8000", "label": "80% of limit" },
      { "value": "10000", "label": "100% of limit" }
    ],
    "require_acknowledgment": false
  }'
```

### Cost Exceeded

Fires when the estimated cost for a billing period crosses a threshold. Specify the `currency` field to match the subscription's billing currency.

```bash theme={null}
curl -X POST https://api.monigo.co/api/v1/alerts?org_id=YOUR_ORG_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "cost_exceeded",
    "scope": "subscription",
    "scope_id": "SUBSCRIPTION_ID",
    "currency": "NGN",
    "thresholds": [
      { "value": "50000", "label": "Budget warning" },
      { "value": "100000", "label": "Budget exceeded" }
    ],
    "require_acknowledgment": true
  }'
```

### Wallet Balance Dropped

Fires when a customer's wallet balance drops below a threshold. Helps you prompt customers to top up before their balance runs out.

```bash theme={null}
curl -X POST https://api.monigo.co/api/v1/alerts?org_id=YOUR_ORG_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "wallet_balance_dropped",
    "scope": "customer",
    "scope_id": "CUSTOMER_ID",
    "currency": "NGN",
    "thresholds": [
      { "value": "5000", "label": "Low balance" },
      { "value": "1000", "label": "Critical balance" }
    ],
    "require_acknowledgment": false
  }'
```

## Plan-Level Alerts

When you set `scope` to `"plan"`, the alert applies to every subscription on that plan. Monigo automatically creates per-subscription tracking states when the alert is evaluated, so you do not need to create individual alerts for each customer.

```bash theme={null}
curl -X POST https://api.monigo.co/api/v1/alerts?org_id=YOUR_ORG_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "usage_exceeded",
    "scope": "plan",
    "scope_id": "PLAN_ID",
    "metric_id": "METRIC_ID",
    "thresholds": [
      { "value": "800", "label": "80%" },
      { "value": "1000", "label": "100%" }
    ],
    "require_acknowledgment": false
  }'
```

## Multiple Thresholds

Each alert supports multiple thresholds, evaluated in order. When the monitored value crosses the first threshold, Monigo fires a notification and advances to monitoring the next threshold. This lets you set up escalating warnings (for example, 80% and 100%) in a single alert definition.

Each threshold has a `value` (the numeric boundary) and an optional `label` (a human-readable description included in webhook payloads).

## Alert Lifecycle

An alert progresses through these states:

1. **Created** -- The alert is defined with its thresholds and begins monitoring.
2. **Triggered** -- The monitored value crosses a threshold. Monigo fires a webhook event and records the triggered state.
3. **Acknowledged** -- If `require_acknowledgment` is `true`, a team member or API call acknowledges the alert. This is recorded for audit purposes.
4. **Reset** -- At the start of each new billing period, triggered states are automatically reset so thresholds can fire again.

## Webhook Events

When thresholds are crossed or alerts change state, Monigo dispatches webhook events to your configured endpoints.

| Event Type           | Fired When                                                               |
| -------------------- | ------------------------------------------------------------------------ |
| `alert.triggered`    | A threshold is crossed for the first time in the current billing period. |
| `alert.acknowledged` | A triggered alert is acknowledged via the API or dashboard.              |
| `alert.resolved`     | The monitored value drops back below the threshold.                      |
| `alert.disabled`     | An alert is disabled via the API or dashboard.                           |

## Managing Alerts

### List Alerts

```bash theme={null}
curl https://api.monigo.co/api/v1/alerts?org_id=YOUR_ORG_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Filter by type, scope, or customer:

```bash theme={null}
curl "https://api.monigo.co/api/v1/alerts?org_id=YOUR_ORG_ID&type=usage_exceeded&scope=plan" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Update Thresholds

```bash theme={null}
curl -X PUT https://api.monigo.co/api/v1/alerts/ALERT_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "thresholds": [
      { "value": "9000", "label": "90%" },
      { "value": "10000", "label": "100%" }
    ]
  }'
```

### Enable or Disable

```bash theme={null}
# Disable
curl -X POST https://api.monigo.co/api/v1/alerts/ALERT_ID/disable \
  -H "Authorization: Bearer YOUR_API_KEY"

# Enable
curl -X POST https://api.monigo.co/api/v1/alerts/ALERT_ID/enable \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Delete

```bash theme={null}
curl -X DELETE https://api.monigo.co/api/v1/alerts/ALERT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Best Practices

* **Use 80%/100% thresholds.** An early warning at 80% gives customers time to adjust before hitting the limit.
* **Enable `require_acknowledgment` for critical alerts.** This ensures someone on your team explicitly reviews cost or usage spikes before they are dismissed.
* **Combine with webhook endpoints.** Route `alert.triggered` events to Slack, PagerDuty, or your internal tooling for real-time visibility.
* **Prefer plan-level alerts over per-subscription alerts.** Plan-level alerts automatically cover all subscribers and reduce configuration overhead.
* **Set wallet balance alerts above zero.** Alerting at a low-but-nonzero balance gives customers a window to top up before service is interrupted.