> ## Documentation Index
> Fetch the complete documentation index at: https://checkly-422f444a-playwright-vs-cypress-2026.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# IcmpMonitor Construct

> Learn how to configure ICMP monitors with the Checkly CLI.

<Tip>
  Learn more about ICMP Monitors in [the ICMP monitor overview](/detect/uptime-monitoring/icmp-monitors/overview).
</Tip>

ICMP monitors check if a host is reachable by sending ICMP Echo Requests (pings). Use them to monitor network connectivity and latency.

<Accordion title="Prerequisites">
  Before creating ICMP Monitors, ensure you have:

  * An initialized Checkly CLI project
  * A hostname or IP address you want to ping
  * Basic understanding of network connectivity (ICMP / ping)

  For additional setup information, see [CLI overview](/cli/overview).
</Accordion>

<CodeGroup>
  ```ts Basic Example theme={null}
  import { Frequency, IcmpMonitor } from "checkly/constructs"

  new IcmpMonitor('icmp-welcome', {
    name: 'Welcome Site Reachability',
    description: "Pings `welcome.checklyhq.com` to verify **host reachability**.",
    frequency: Frequency.EVERY_1M,
    request: {
      hostname: 'welcome.checklyhq.com',
    },
    degradedPacketLossThreshold: 20, // percentage
    maxPacketLossThreshold: 30, // percentage
  })
  ```

  ```ts Advanced Example theme={null}
  import { Frequency, IcmpAssertionBuilder, IcmpMonitor } from "checkly/constructs"

  new IcmpMonitor('cloudflare-dns-icmp', {
    name: 'Cloudflare DNS ICMP Monitor',
    description: "Cloudflare DNS reachability and latency check.",
    activated: true,
    frequency: Frequency.EVERY_1M,
    maxPacketLossThreshold: 20, // percentage
    degradedPacketLossThreshold: 10,
    request: {
      hostname: '1.1.1.1',
      pingCount: 20,
      assertions: [
        IcmpAssertionBuilder.latency('avg').lessThan(100),
        IcmpAssertionBuilder.latency('max').lessThan(200),
      ]
    }
  })
  ```
</CodeGroup>

## Configuration

ICMP monitors have their own ICMP-specific settings, plus the standard monitor options shared across all check types.

<Tabs>
  <Tab title="ICMP Monitor Settings">
    | Parameter | Type | Required | Default | Description |
    | - | - | - | - | - |
    | `request` | `object` | ✅ | - | ICMP request configuration object |
    | `degradedPacketLossThreshold` | `number` | ❌ | `10` | Packet loss percentage at which the monitor is marked as degraded |
    | `maxPacketLossThreshold` | `number` | ❌ | `20` | Packet loss percentage at which the monitor is marked as failed |
  </Tab>

  <Tab title="General Monitor Settings">
    | Property | Type | Required | Default | Description |
    | - | - | - | - | - |
    | `name` | `string` | ✅ | - | Friendly name for your monitor |
    | `description` | `string` | ❌ | `null` | A description of the monitor. Supports markdown. Max 500 characters |
    | `activated` | `boolean` | ❌ | `true` | Whether the monitor is enabled |
    | `alertChannels` | `Array<AlertChannel \| AlertChannelRef>` | ❌ | `[]` | Array of AlertChannel objects for notifications |
    | `alertEscalationPolicy` | `AlertEscalationPolicy` | ❌ | - | Advanced alert escalation settings |
    | `frequency` | `Frequency` | ❌ | `EVERY_10M` | How often to run your monitor |
    | `group` | `CheckGroupV1` `CheckGroupV2` | ❌ | - | The CheckGroup this monitor belongs to |
    | `locations` | `string[]` | ❌ | `[]` | Array of public location codes |
    | `privateLocations` | `string[]` | ❌ | `[]` | Array of Private Location slugs |
    | `muted` | `boolean` | ❌ | `false` | Whether alert notifications are muted |
    | `tags` | `string[]` | ❌ | `[]` | Array of tags to organize monitors |
    | `testOnly` | `boolean` | ❌ | `false` | Only run with test, not during deploy |
    | `retryStrategy` | `RetryStrategy` | ❌ | - | Strategy for configuring retries |
    | `runParallel` | `boolean` | ❌ | `false` | Run monitors in parallel or round-robin |
    | `triggerIncident` | `IncidentTrigger` | ❌ | - | Create and resolve an incident based on the check's alert configuration |
  </Tab>
</Tabs>

### `IcmpMonitor` Options

<ResponseField name="request" type="object" required>
  ICMP request configuration, including ping settings and response validation.

  **Usage:**

  ```ts theme={null}
  new IcmpMonitor('icmp-monitor', {
    name: 'ICMP Latency Monitor',
    request: {
      hostname: 'api.checklyhq.com',
      pingCount: 15,
      assertions: [
        IcmpAssertionBuilder.latency('avg').lessThan(100),
      ]
    }
  })
  ```

  **Parameters:**

  | Parameter | Type | Required | Default | Description |
  | - | - | - | - | - |
  | `hostname` | `string` | ✅ | - | The target host (domain name or IP address) |
  | `pingCount` | `number` | ❌ | `10` | Number of ICMP Echo Request packets to send per check run (1-50, default: 10) |
  | `assertions` | `IcmpAssertion[]` | ❌ | `[]` | Response assertions using the `IcmpAssertionBuilder` |
  | `ipFamily` | `string` | ❌ | `IPv4` | IP family selection (IPv4, IPv6) |
</ResponseField>

<ResponseField name="degradedPacketLossThreshold" type="number" default="10">
  Packet loss percentage at which the monitor is marked as degraded (warning state).

  **Usage:**

  ```ts highlight={3} theme={null}
  new IcmpMonitor("icmp-performance-tiers", {
    name: "ICMP Performance Tiers",
    degradedPacketLossThreshold: 15, // Warn at 15%
    request: {
      hostname: '1.1.1.1',
      pingCount: 20,
    }
  })
  ```
</ResponseField>

<ResponseField name="maxPacketLossThreshold" type="number" default="20">
  Packet loss percentage at which the monitor is marked as failed

  **Usage:**

  ```ts highlight={3} theme={null}
  new IcmpMonitor("icmp-performance-tiers", {
    name: "ICMP Performance Tiers",
    maxPacketLossThreshold: 25, // Fail at 25%
    request: {
      hostname: '1.1.1.1',
      pingCount: 20,
    }
  })
  ```
</ResponseField>

### `IcmpMonitor` Assertions

Assertions for ICMP monitors can be defined using the `IcmpAssertionBuilder`. The following sources are available:

* `latency(property)`: Validate round-trip time (RTT) for ICMP pings. The property parameter is required and must be one of: `avg`, `min`, `max`, or `stdDev`
* `jsonResponse(property?)`: Assert against the [JSON response structure](/detect/uptime-monitoring/icmp-monitors/configuration#json-response-schemas). This allows you to target specific fields using JSON path assertions

Here are some examples:

* Assert the average latency is below a threshold

```ts theme={null}
IcmpAssertionBuilder.latency('avg').lessThan(100)
// Equivalent to:
{ source: 'LATENCY', property: 'avg', comparison: 'LESS_THAN', target: '100' }
```

* Assert against specific JSON fields in the response

```ts theme={null}
IcmpAssertionBuilder.jsonResponse('$.packetsReceived').equals(10)
// Equivalent to:
{ source: 'JSON_RESPONSE', property: '$.packetsReceived', comparison: 'EQUALS', target: '10' }
```

Learn more in our docs on [Assertions](/detect/assertions).

### General Monitor Options

<ResponseField name="name" type="string" required>
  Friendly name for your ICMP Monitor that will be displayed in the Checkly dashboard and used in notifications.

  **Usage:**

  ```ts highlight={2} theme={null}
  new IcmpMonitor("my-monitor", {
    name: "ICMP Ping Monitor",
    /* More options ... */
  })
  ```
</ResponseField>

<ResponseField name="frequency" type="Frequency">
  How often the ICMP Monitor should run. Use the `Frequency` enum to set the check interval.

  **Usage:**

  ```ts highlight={3} theme={null}
  new IcmpMonitor("my-monitor", {
    name: "ICMP Ping Monitor",
    frequency: Frequency.EVERY_1M,
    /* More options ... */
  })
  ```

  **Available frequencies**: `EVERY_10S`, `EVERY_20S`, `EVERY_30S`, `EVERY_1M`, `EVERY_2M`, `EVERY_5M`, `EVERY_10M`, `EVERY_15M`, `EVERY_30M`, `EVERY_1H`, `EVERY_2H`, `EVERY_3H`, `EVERY_6H`, `EVERY_12H`, `EVERY_24H`
</ResponseField>

<ResponseField name="locations" type="string[]" default="[]">
  Array of [public location codes](/concepts/locations/#public-locations) where the ICMP Monitor should run from. Multiple locations provide geographic coverage and help detect regional network issues.

  **Usage:**

  ```ts highlight={3} theme={null}
  new IcmpMonitor("global-icmp-monitor", {
    name: "ICMP Ping Monitor",
    locations: ["us-east-1", "eu-central-1", "ap-southeast-1"]
  })
  ```
</ResponseField>

<ResponseField name="activated" type="boolean" default="true">
  Whether the ICMP Monitor is enabled and will run according to its schedule.

  **Usage:**

  ```ts highlight={3} theme={null}
  new IcmpMonitor("my-monitor", {
    name: "ICMP Ping Monitor",
    activated: false // Disabled monitor
  })
  ```
</ResponseField>