# Alert delays & escalation ladders

Not every contact should hear about a Down the instant it happens. Escalation lets you delay a contact's alert
and, for a longer outage, bring in further contacts only if the problem persists.

## What it is and when to use it

Give your fastest-reacting contact (a team chat channel, an on-call phone) no delay, and give slower or
more disruptive channels (a manager's phone call) a delay - so only an outage that's actually serious enough
to matter reaches them. This turns a flat list of contacts into a ladder that escalates on its own.

## Settings reference

| Setting (UI label) | API field (v2) | Type / allowed values | Default | Plan limits | What it does for you |
|---|---|---|---|---|---|
| Alert delay | `alertDelay` (on the contact) | Minutes - **one of exactly ten values**: `0`, `3`, `5`, `15`, `30`, `60`, `180`, `360`, `720`, `1440` | `0` (instant) | - | How long a confirmed Down must persist, continuously, before this contact is notified |

The ten values read as: instant, 3 minutes, 5 minutes, 15 minutes, 30 minutes, 1 hour, 3 hours, 6 hours, 12
hours, and 24 hours. **This is a fixed, closed list** - it's not a slider with arbitrary minutes; sending any
other number is refused with `422 invalid_alert_delay` (the legacy door's equivalent is `WrongAlertDelay`).
There's no value between 30 minutes and 1 hour, or above 24 hours.

## How a delay works

Each contact has its own alert delay - it lives **on the contact**, not on the subscription or the monitor, so
the same behavior applies everywhere that contact is subscribed:

1. Contacts with a delay of `0` are notified the moment a Down is confirmed.
2. A contact with a delay only gets notified once the outage has lasted that long, continuously. If the monitor
   recovers before the delay elapses, that contact never hears about the Down at all - which is the point: a
   delay filters out outages too short to matter to that contact.

## Building an escalation ladder

Give contacts increasing delays, chosen from the ten allowed values, to build a ladder - for example:

| Tier | Contact | Delay |
|---|---|---|
| 1 | Team Slack channel | Instant (`0`) |
| 2 | On-call engineer (SMS) | 5 minutes |
| 3 | Engineering manager (voice call) | 30 minutes |

A short blip only reaches tier 1. An outage that drags on pulls in tier 2, then tier 3 - each later tier is a
sign the problem is getting more serious.

## Repeat alerts while it's still down

Combine a delay with a [still-down (repeatedly down) subscription](/alerts/subscriptions/#event-types) to have
a contact re-notified at intervals - roughly once per monitoring interval - for as long as the outage continues,
instead of a single Down alert followed by silence. The alert delay only gates the *first* Down alert to that
contact; it does not throttle how often still-down repeats afterward.

## How recovery is handled

When the monitor comes back up, HostTracker sends the Up alert only to the tiers that had **already elapsed** -
that is, contacts that were actually notified of the Down. A tier whose delay never elapsed (because the outage
was too short to reach it) never received the Down alert, so it isn't sent the Up alert either. This keeps the
"how bad did this get" story consistent for every contact: you only hear the resolution for problems you were
told about.

## Set it up in the app

1. Open the contact and expand **Main Settings**.
2. Drag the **Alert delay** slider - the track is marked at 5 minutes, 30 minutes and 3 hours, with instant at
   one end and 24 hours at the other.
3. Save.

## Do it with the API or MCP

```
PATCH /contact/{id}
{ "alertDelay": 30 }
```

MCP: `update_contact(id, alertDelay=30)`, or set it at creation with `create_contact(..., alertDelay=180)`.
There's no separate escalation-ladder resource to create - a ladder is just several contacts, each with its own
`alertDelay`, subscribed to the same monitor.

## Limits and gotchas

- **Sending a value outside the ten-item ladder is refused, not rounded** - there is no 45-minute or 2-hour
  option; pick the nearest allowed value.
- A contact's delay applies **per subscription** implicitly - since the delay lives on the contact, you can't
  give the same contact a different delay for two different monitors. Create a second contact (same address,
  different delay) if you need that.
- Active hours and alert delay are independent and both apply: a contact outside its active window still won't
  receive the alert even once its delay has elapsed - see [Active hours](/alerts/active-hours/).

## Related

- [Subscriptions: alert vs report](/alerts/subscriptions/)
- [Active hours](/alerts/active-hours/)
- [Test a contact](/alerts/test-a-contact/)
- [What a contact is](/alerts/contacts/)