Monitoring

Alerting: thresholds, reminders and suppression

How a failing check becomes an alert — consecutive-failure thresholds, latency alerts, the fixed reminder schedule, dependencies and what suppresses a notification.

Alerting is state-based. Each monitor has a status (up, down, or unknown before its first result) and a notification is sent only when that status flips. The knobs below decide how fast it flips and where the notification goes; the destinations page covers the channels themselves.

Thresholds

Field	Default	What it does
`failure_threshold`	1	Consecutive failed checks before the monitor is down. `2` on a 30-second interval means a real outage pages within a minute and a single dropped packet never does.
`success_threshold`	1	Consecutive successful checks before it is up again. Raise it for targets that flap during recovery.
`alert_latency_ms`	off	HTTP and multi-step only. Notify when a successful check exceeds this many milliseconds for `failure_threshold` consecutive checks. The monitor stays up; the event is `performance_anomaly`, and `performance_recovered` follows. Maximum 600000.
`max_packet_loss_percent`	100	ICMP only. Loss at or above this percentage counts the check as failed.
`cert_expiry_alert_days`	7	TLS monitors. Fire `cert_expiring` this many days before the certificate's notAfter: 1, 3, 7, 14 or 30. `cert_expiry_alert_disabled` turns it off.
`alert_on_continued_step_failure`	off	Multi-step API only. Keep notifying while later steps continue to fail, not only on the first.

A monitor that has never succeeded — broken from the moment it was created — goes unknown → down without alerting, so a typo in a new target does not page the on-call. Fix the target and the first success starts normal alerting.

Where notifications go

Email is the built-in channel (alert_channels: ["email"]). With no alert_emails, every verified member of the organization is emailed; with a list, only those addresses.
Notification destinations — Slack, Teams, Discord, Telegram, PagerDuty, Opsgenie, incident.io, Rootly, generic webhooks — are configured once per organization and attached to a monitor through alert_destination_ids (up to 20). Each destination has its own event filter.
Custom subject and body (alert_custom_subject ≤ 200 chars, alert_custom_body ≤ 2000) replace the default text. Placeholders: {{monitor_name}}, {{status}}, {{from_status}}, {{message}}, {{monitor_url}}, {{target}}, {{environment}}, {{http_status}}, {{response_time}}, {{downtime}}, {{company_name}}.

alerting.jsonjson

{
  "config": {
    "failure_threshold": 2,
    "success_threshold": 2,
    "alert_latency_ms": 1500,
    "alert_channels": ["email"],
    "alert_emails": ["oncall@example.com"],
    "alert_destination_ids": ["8c2f…", "d41b…"],
    "alert_custom_subject": "[{{status}}] {{monitor_name}} — {{message}}"
  }
}

Reminders while something stays down

There is no escalation policy to configure. A monitor that stays down gets a reminder to the same destinations at 4 hours, 8 hours, and then every 24 hours until it recovers. Reminders reuse the original down event and dedup key, so PagerDuty and Opsgenie update the existing alert instead of opening a second one, and they use the default text rather than a custom template. The cycle resets on recovery.

Dependencies

Set a monitor's dependencies with PUT /api/v1/monitors/{id}/dependencies. When a monitor goes down while a dependency is already down, its down notification is suppressed and the dependency is recorded as the root cause on the incident. Recoveries are never suppressed, so you always learn when the dependent service is back.

What suppresses a notification

An active maintenance window covering the monitor blocks incident creation; with suppress_notifications it silences the notifications too.
A dependency that is already down (above).
A destination whose event filter does not include the event.
A flap that never reaches failure_threshold.

Seeing the gaps

The Alerts page lists everything currently alerting, recent alerting changes, and — importantly — monitors with no alert channel at all, so a monitor that was created by API without a destination does not sit silent.