Learn more about alert escalation policies in the alerts configuration.
Use alert escalation policies to control when and how often you receive alerts when checks start failing, degrade, or recover. This helps you fine-tune your alerting to reduce noise and ensure timely alerts. 
import { AlertEscalationBuilder, ApiCheck } from "checkly/constructs"

new ApiCheck("run-based-alert-check", {
  name: "Check With Run-Based Escalation",
  alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(
    2, // Alert after 2 consecutive failures
    { interval: 5, amount: 2 }, // Send 2 reminders, 5 minutes apart
    { enabled: true, percentage: 50 } // Alert if 50% of parallel runs fail
  ),
  request: {
    method: "GET",
    url: "https://api.example.com/health",
  },
})

​
Configuration

Configure your alert escalation policies using the AlertEscalationBuilder, which provides helper methods for the different escalation strategies:
MethodDescriptionParameters
runBasedEscalation()Alert after N consecutive failed runs(failedRuns, reminders, parallelRunFailureThreshold)
timeBasedEscalation()Alert after N minutes of continuous failures(minutesFailing, reminders, parallelRunFailureThreshold)

​
Alert Escalation Builder Methods

​
runBasedEscalation
function
required
Creates an alert escalation policy that triggers after a specified number of consecutive failed runs.Usage:
AlertEscalationBuilder.runBasedEscalation(
  failedRuns,
  reminders,
  parallelRunFailureThreshold
)
Parameters:
ParameterTypeRequiredDefaultDescription
failedRunsnumber✅1Number of consecutive failed runs before alerting
remindersobject❌-Reminder notification configuration
parallelRunFailureThresholdobject❌-Parallel run failure percentage threshold
Examples:
// Alert immediately on first failure
const immediateAlert = AlertEscalationBuilder.runBasedEscalation(
  1, // Alert after 1 failed run
  { interval: 5, amount: 0 }, // No reminders
)

new ApiCheck("critical-service-check", {
  name: "Critical Service Check",
  alertEscalationPolicy: immediateAlert,
  request: {
    method: "GET",
    url: "https://api.example.com/critical",
  },
})
Use cases: Immediate alerting and noise reduction for flaky services.
​
timeBasedEscalation
function
required
Creates an alert escalation policy that triggers after a specified duration of continuous failures.Usage:
AlertEscalationBuilder.timeBasedEscalation(
  minutesFailing,
  reminders,
  parallelRunFailureThreshold
)
Parameters:
ParameterTypeRequiredDescription
minutesFailingnumber✅Minutes of continuous failures before alerting
remindersobject❌Reminder notification configuration
parallelRunFailureThresholdobject❌Parallel run failure percentage threshold
Examples:
// Wait for batch jobs or slow services
const timeBasedAlert = AlertEscalationBuilder.timeBasedEscalation(
  15, // Alert after 15 minutes of failures
  { interval: 10, amount: 3 } // 3 reminders, 10 minutes apart
)

new ApiCheck("batch-job-check", {
  name: "Batch Job Monitoring",
  frequency: Frequency.EVERY_5M,
  alertEscalationPolicy: timeBasedAlert,
  request: {
    method: "GET",
    url: "https://api.example.com/batch-status",
  },
})
Use cases: Batch job monitoring, slow services, time-sensitive operations.
​
reminders
object
Configure reminder notifications while an alert is active.Usage:
reminders: {
  interval: 10, // Send reminder every 10 minutes
  amount: 5     // Send up to 5 reminders
}
Parameters:
ParameterTypeRequiredDefaultDescription
intervalnumber❌5Minutes between reminder notifications: 5, 10, 15, 30
amountnumber❌0Number of reminder notifications to send: 0, 1, 2, 3, 4, 5, 100000
Examples:
// Alert once, no reminders
reminders: {
  interval: 5,
  amount: 0
}
Use cases: Alert fatigue prevention, escalation management, notification frequency control.
​
parallelRunFailureThreshold
object
Configure threshold for checks running in parallel across multiple locations.Usage:
parallelRunFailureThreshold: {
  enabled: true,
  percentage: 60 // Alert if 60% of parallel runs fail
}
Parameters:
ParameterTypeRequiredDefaultDescription
enabledboolean✅falseWhether to use parallel run failure threshold
percentagenumber❌10Percentage of parallel runs that must fail (10-100, in increments of 10)
Examples:
// Only alert if majority of regions fail
const regionalAlert = AlertEscalationBuilder.runBasedEscalation(
  2, // After 2 consecutive failures
  { interval: 10, amount: 3 },
  { enabled: true, percentage: 70 } // 70% of regions must fail
)

new ApiCheck("global-service-check", {
  name: "Global Service Check",
  locations: ["us-east-1", "us-west-2", "eu-west-1", "ap-southeast-1"],
  runParallel: true,
  alertEscalationPolicy: regionalAlert,
  request: {
    method: "GET",
    url: "https://global-api.example.com/health",
  },
})
Use cases: Multi-region monitoring, CDN availability, redundant service checking.

​
Examples

import {
  AlertEscalationBuilder,
  ApiCheck,
  CheckGroupV2,
} from "checkly/constructs"

const groupAlertPolicy = AlertEscalationBuilder.runBasedEscalation(
  3, // Alert after 3 consecutive failures
  { interval: 15, amount: 3 }, // 3 reminders, 15 minutes apart
  { enabled: true, percentage: 60 }
)

const monitoringGroup = new CheckGroupV2("monitoring-group", {
  name: "Production Monitoring",
  alertEscalationPolicy: groupAlertPolicy, // Applies to all checks in group
  locations: ["us-east-1", "eu-west-1"],
  runParallel: true,
})

new ApiCheck("group-api-check", {
  name: "API Check with Group Alert Policy",
  group: monitoringGroup, // Inherits alert policy from group
  request: {
    method: "GET",
    url: "https://api.example.com/endpoint",
  },
})
Reminder Limits: Be cautious with reminder settings. Too many reminders can lead to alert fatigue, while too few might cause important issues to be overlooked.
Parallel Run Thresholds: Only use parallel run failure thresholds for checks that run in multiple locations simultaneously (runParallel: true).