# Alert rules
URL: https://musicapi.com/docs/webhooks/alert-rules.md

> Get an email or a PagerDuty page when the error rate, the sign-in failure rate, the transfer throughput or a service goes bad. Metrics, windows and channels.

Product: MusicAPI Managed Transfers. Section: Webhooks and alerts.

An alert rule watches one metric of your account over a time window. When the metric crosses its threshold, the rule fires and notifies you once. Set rules up under **Analytics → Reliability** in the dashboard.

Alert rules belong to Managed Transfers. A rule of an account with Managed Transfers off is not checked.

## Metrics

| Metric                 | What it measures                                                        | Unit             | Fires when the value is |
| ---------------------- | ----------------------------------------------------------------------- | ---------------- | ----------------------- |
| `destinationErrorRate` | The share of your API calls that failed in the window                   | percent          | above the threshold     |
| `authFailureRate`      | The share of sign-in attempts that did not end in a connected account   | percent          | above the threshold     |
| `transferThroughput`   | Items your transfers really added, per minute, averaged over the window | items per minute | **below** the threshold |
| `integrationDown`      | Services whose every call failed in the window                          | count            | above the threshold     |

The two rate metrics need at least **10 requests** in the window before they can fire. Two failed calls out of two say nothing. `transferThroughput` is checked only while a transfer of your account runs, so a quiet night does not page you. `integrationDown` counts a service only when it had enough calls, all of them failed. A rule fires when the value is strictly above (or, for throughput, strictly below) the threshold: `integrationDown` with threshold `0` fires for the first service that is down.

## Windows and checks

- The window is 1 to 1,440 minutes (one day). The default is 5 minutes.
- MusicAPI checks every rule **every 5 minutes**.
- A rule moves between `ok` and `firing`. Only the step into `firing` notifies you. The step back to `ok` is recorded, with no message.
- Any edit to what a rule measures (metric, threshold, window) puts it back to `ok`.

## Channels

| Channel     | Config                                                                                                              | Status                                                                              |
| ----------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `email`     | `email`: the address to notify. Required.                                                                           | Sends                                                                               |
| `pagerduty` | `routingKey`: an Events API v2 routing key. Optional when your account has a PagerDuty routing key in its settings. | Sends. A **test page** button sends a harmless test incident to your account's key. |
| `slack`     | `webhookUrl`: a Slack incoming webhook URL                                                                          | Stored only. Nothing is sent to Slack yet.                                          |

Secrets are write-only. The dashboard and the API show them masked. An empty field on edit keeps the stored value.

A rule that could reach nobody is refused: an email rule without an address, or a PagerDuty rule with no key on the rule and none on the account.

## Examples

| Rule                         | Metric                 | Threshold | Window |
| ---------------------------- | ---------------------- | --------- | ------ |
| "More than 5% of calls fail" | `destinationErrorRate` | 5         | 15     |
| "A third of sign-ins fail"   | `authFailureRate`      | 33        | 30     |
| "Transfers stall"            | `transferThroughput`   | 10        | 30     |
| "A service is down"          | `integrationDown`      | 0         | 15     |

## Set them up with an AI agent

The [MusicAPI MCP server](https://musicapi.com/docs/ai/mcp-server.md) has `list_alert_rules`, `create_alert_rule`, `update_alert_rule` and `delete_alert_rule`.