> ## Documentation Index
> Fetch the complete documentation index at: https://checkly-422f444a-herve-close-confirmed-docs-gaps.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 |
    | `intent` | `CheckIntent` | ❌ | - | Structured guidance for root cause analysis and check repair. See [General Monitor Options](#general-monitor-options). |
    | `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>

<ResponseField name="intent" type="CheckIntent">
  Describe what your check is intended to verify and the behavior that should be preserved. Checkly uses intent for root cause analysis across all check types. It is separate from `description` and does not replace executable assertions.

  <Note>
    Intent is used for [automatic repair](/resolve/automatic-check-repair) only for Browser and Multistep Checks.
  </Note>

  The object accepts the following fields:

  | Field | Type | Required | Description |
  | - | - | - | - |
  | `goal` | `string` | Yes | The outcome your check should verify. Must contain 1–2,000 characters after trimming. |
  | `constraints` | `CheckIntentConstraint[]` | No | Outcomes and guardrails that refine the goal. Omitted constraints become an empty array. |

  Each constraint has a required `type` and `statement`:

  * `REQUIRED_OUTCOME`: an outcome the check must verify.
  * `MUST_PRESERVE`: behavior or an assertion that should be preserved when repairing the check.

  Each `statement` must contain 1–1,000 characters after trimming. You can specify at most 20 constraints of each type. The CLI trims leading and trailing whitespace from the goal and statements and rejects unknown fields.

  For example, configure intent on a Browser Check:

  ```ts theme={null}
  import { BrowserCheck } from "checkly/constructs"

  new BrowserCheck("dashboard-intent", {
    name: "Authenticated dashboard",
    code: {
      entrypoint: "./dashboard.spec.ts",
    },
    intent: {
      goal: "Verify that authenticated users can open the dashboard.",
      constraints: [
        {
          type: "REQUIRED_OUTCOME",
          statement: "Authentication succeeds for a valid user.",
        },
        {
          type: "MUST_PRESERVE",
          statement: "Do not remove or weaken the authentication assertion.",
        },
      ],
    },
  })
  ```
</ResponseField>


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