# Alerts

Notifications fire on something the platform did: a deploy failed, a server went offline. Alerts fire on what your application is doing — it started answering with 500s, it got ten times slower, it isn't running. They arrive through the same [channels](/docs/notifications), and the all-clear is always sent.

Admins set them up under **Settings → Alerts**. A rule made there covers every service of the organization, including ones added later.

## What a rule can watch

| Measure | Fires when |
| --- | --- |
| Failed requests | More than `n`% of requests are answered with a 5xx. |
| Response time | The slowest 5% of requests take longer than `n` milliseconds. |
| Memory | The service uses more than `n`% of the memory its [size](/docs/containers) gives it. |
| Not running | The service is crashed, failing its health check, or its [volume](/docs/volumes) is full. |

Each rule has a threshold and a window: the measure has to stay past the threshold for the **whole** window before anything is said.

## One service on its own

Open a service: the top of its **Overview** says what watches it, and **Tell me when it breaks** adds the usual three — failed requests, slow responses and not running — for that service alone. Their thresholds are changed back in **Settings → Alerts**, where every rule is listed with the service it watches.

While a rule is past its threshold, the service's Overview says so and since when.

## In alf.toml

A service's alerts can live beside its code, in [alf.toml](/docs/alf-toml#alerts):

```toml
[services.web.alerts]
error_rate = "5%"
response_time = "3s for 10m"
down = true
```

Each deploy makes or sets them; one changed in the dashboard since is asked about, not put back.

## Why it stays quiet

Alerting earns its keep by being believed, so the rules hold back:

- A bad minute says nothing: the measure has to stay past the threshold for the whole window.
- Fewer than 20 requests in the window and error rate and response time aren't judged at all — one failure in three requests is noise.
- A rule that keeps firing repeats at most hourly.
- The all-clear is sent when it recovers, so nobody is left wondering.

## From a coding agent

Agents have the same over MCP: `watch_service` makes the usual three for a service, `create_alert`, `update_alert` and `delete_alert` do the rest, and `list_alerts` says what is firing. An agent can check with `list_notification_channels` that a channel listens for alerts, and add one you give it the address for. See [Agent tools](/docs/agent-tools).

## Through the API

```bash
curl -X POST https://api.runalf.com/api/v1/organizations/$ORG/alerts \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"measure":"error_rate","threshold":5,"window_minutes":5}'
```

`measure` is one of `error_rate`, `p95_ms`, `memory_percent` or `failing`; `service_id` narrows a rule to one service. `POST /organizations/$ORG/alerts/watch` makes the usual three in one go. See the [API reference](/docs/api).