> ## Documentation Index
> Fetch the complete documentation index at: https://www.checklyhq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Alert Escalation Policy Construct

> Learn how to configure alert escalation policies with the Checkly CLI.

> [!TIP]
>
> Learn more about alert escalation policies in [the alerts configuration](https://www.checklyhq.com/docs/communicate/alerts/configuration.md#escalation-strategies).

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.

```ts Run-Based Escalation theme={null}
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",
  },
})
```

```ts Time-Based Escalation theme={null}
import { ApiCheck, AlertEscalationBuilder } from "checkly/constructs"

new ApiCheck("time-based-alert-check", {
  name: "Check With Time-Based Escalation",
  alertEscalationPolicy: AlertEscalationBuilder.timeBasedEscalation(
    10, // Alert after 10 minutes of failures
    { interval: 15, amount: 3 }, // Send 3 reminders, 15 minutes apart
    { enabled: false, percentage: 30 } // Parallel run threshold disabled
  ),
  request: {
    method: "GET",
    url: "https://api.example.com/critical-endpoint",
  },
})
```

## 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

**runBasedEscalation** `function` *required*

Creates an alert escalation policy that triggers after a specified number of consecutive failed runs.

**Usage:**

```ts theme={null}
AlertEscalationBuilder.runBasedEscalation(
  failedRuns,
  reminders,
  parallelRunFailureThreshold
)
```

**Parameters:**

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `failedRuns` | `number` | ✅ | 1 | Number of consecutive failed runs before alerting |
| `reminders` | `object` | ❌ | - | Reminder notification configuration |
| `parallelRunFailureThreshold` | `object` | ❌ | - | Parallel run failure percentage threshold |

**Examples:**

```ts Immediate Alert theme={null}
// 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",
  },
})
```

```ts Conservative Alert theme={null}
// Wait for multiple failures before alerting
const conservativeAlert = AlertEscalationBuilder.runBasedEscalation(
  5, // Alert after 5 consecutive failures
  { interval: 30, amount: 2 }, // 2 reminders, 30 minutes apart
  { enabled: true, percentage: 80 } // Only if 80% of parallel runs fail
)

new ApiCheck("flaky-service-check", {
  name: "Flaky Service Check",
  alertEscalationPolicy: conservativeAlert,
  locations: ["us-east-1", "eu-west-1", "ap-southeast-1"],
  runParallel: true,
  request: {
    method: "GET",
    url: "https://api.example.com/sometimes-flaky",
  },
})
```

**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:**

```ts theme={null}
AlertEscalationBuilder.timeBasedEscalation(
  minutesFailing,
  reminders,
  parallelRunFailureThreshold
)
```

**Parameters:**

| Parameter | Type | Required | Description |
| - | - | - | - |
| `minutesFailing` | `number` | ✅ | Minutes of continuous failures before alerting |
| `reminders` | `object` | ❌ | Reminder notification configuration |
| `parallelRunFailureThreshold` | `object` | ❌ | Parallel run failure percentage threshold |

**Examples:**

```ts Alert after 15 minutes theme={null}
// 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:**

```ts theme={null}
reminders: {
  interval: 10, // Send reminder every 10 minutes
  amount: 5     // Send up to 5 reminders
}
```

**Parameters:**

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `interval` | `number` | ❌ | `5` | Minutes between reminder notifications: `5`, `10`, `15`, `30` |
| `amount` | `number` | ❌ | `0` | Number of reminder notifications to send: `0`, `1`, `2`, `3`, `4`, `5`, `100000` |

**Examples:**

```ts No Reminders theme={null}
// Alert once, no reminders
reminders: {
  interval: 5,
  amount: 0
}
```

```ts Frequent Reminders theme={null}
// Aggressive reminder schedule
reminders: {
  interval: 15, // Every 15 minutes
  amount: 5   // Up to 5 reminders
}
```

```ts Conservative Reminders theme={null}
// Occasional reminders to avoid spam
reminders: {
  interval: 30, // Every 30 minutes
  amount: 2     // Only 2 reminders
}
```

**Use cases**: Alert fatigue prevention, escalation management, notification frequency control.

**parallelRunFailureThreshold** `object`

Configure threshold for checks running in parallel across multiple locations.

**Usage:**

```ts theme={null}
parallelRunFailureThreshold: {
  enabled: true,
  percentage: 60 // Alert if 60% of parallel runs fail
}
```

**Parameters:**

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `enabled` | `boolean` | ✅ | `false` | Whether to use parallel run failure threshold |
| `percentage` | `number` | ❌ | `10` | Percentage of parallel runs that must fail (10-100, in increments of 10) |

**Examples:**

```ts Regional Redundancy theme={null}
// 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",
  },
})
```

```ts CDN Monitoring theme={null}
// Alert if 10% of CDN edges are failing
const cdnAlert = AlertEscalationBuilder.runBasedEscalation(
  1, // Immediate on failure
  { interval: 5, amount: 2 },
  { enabled: true, percentage: 10 } // 10% of edges must fail
)

new UrlMonitor("cdn-availability", {
  name: "CDN Edge Availability",
  locations: ["us-east-1", "us-west-2", "eu-west-1", "ap-southeast-1"],
  runParallel: true,
  alertEscalationPolicy: cdnAlert,
  request: {
    url: "https://cdn.example.com/health",
  },
})
```

**Use cases**: Multi-region monitoring, CDN availability, redundant service checking.

## Examples

```ts Group-Level Policy theme={null}
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",
  },
})
```

> [!WARNING]
>
> **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.

> [!NOTE]
>
> **Parallel Run Thresholds**: Only use parallel run failure thresholds for checks that run in multiple locations simultaneously (`runParallel: true`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.