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. Run-Based Escalation
Time-Based Escalation
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: Method Description Parameters 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 Creates an alert escalation policy that triggers after a specified number of consecutive failed runs. Usage: AlertEscalationBuilder . runBasedEscalation ( failedRuns , reminders , parallelRunFailureThreshold )
Parameters: Parameter Type Required Default Description failedRunsnumber✅ 1 Number of consecutive failed runs before alerting remindersobject❌ - Reminder notification configuration parallelRunFailureThresholdobject❌ - Parallel run failure percentage threshold
Examples: Immediate Alert
Conservative Alert
// 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.Creates an alert escalation policy that triggers after a specified duration of continuous failures. Usage: AlertEscalationBuilder . timeBasedEscalation ( minutesFailing , reminders , parallelRunFailureThreshold )
Parameters: Parameter Type Required Description 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.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: Parameter Type Required Default Description intervalnumber❌ 5Minutes between reminder notifications: 5, 10, 15, 30 amountnumber❌ 0Number of reminder notifications to send: 0, 1, 2, 3, 4, 5, 100000
Examples: No Reminders
Frequent Reminders
Conservative Reminders
// Alert once, no reminders reminders : { interval : 5 , amount : 0 }
Use cases : Alert fatigue prevention, escalation management, notification frequency control.parallelRunFailureThreshold
Configure threshold for checks running in parallel across multiple locations. Usage: parallelRunFailureThreshold : { enabled : true , percentage : 60 // Alert if 60% of parallel runs fail }
Parameters: Parameter Type Required Default Description enabledboolean✅ falseWhether to use parallel run failure threshold percentagenumber❌ 10Percentage of parallel runs that must fail (10-100, in increments of 10)
Examples: Regional Redundancy
CDN Monitoring
// 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).
