---
title: "Create an ICMP monitor"
method: POST
path: "/v1/checks/icmp"
tags: ["Monitors"]
---

# Create an ICMP monitor

`POST /v1/checks/icmp`

Creates a new ICMP monitor. Will return a `402` when you are over the limit of your plan.
    When using the `globalAlertSetting`, the `alertSetting` can be `null`

## Query parameters

- `autoAssignAlerts` boolean — Determines whether a new check will automatically be added as a subscriber to all existing alert channels when it gets created.

## Headers

- `x-checkly-account` string — Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general

## Request body

- IcmpMonitorCreate
  - `name` string, required — The name of the check.
  - `activated` boolean — Determines if the check is running or not.
  - `muted` boolean — Determines if any notifications will be send out when a check fails and/or recovers.
  - `doubleCheck` boolean — [Deprecated] Retry failed check runs. This property is deprecated, and `retryStrategy` can be used instead.
  - `shouldFail` boolean — Allows to invert the behaviour of when a check is considered to fail. Allows for validating error status like 404.
  - `locations` Model164[], nullable — An array of one or more data center locations where to run this check.
  - `tags` string[] — Tags for organizing and filtering checks.
  - `alertSettings` AlertSettings — Alert settings.
    - `escalationType` 'RUN_BASED' | 'TIME_BASED' — Determines what type of escalation to use.
    - `reminders` AlertSettingsReminders
      - `amount` 0 | 1 | 2 | 3 | 4 | 5 | 100000 — How many reminders to send out after the initial alert notification.
      - `interval` 1 | 2 | 3 | 4 | 5 | 10 | 15 | 30 — At what interval the reminders should be send.
    - `sslCertificates` AlertSettingsSSLCertificates — [DEPRECATED] `sslCertificates` is deprecated and is not longer used. Please ignore it, will be removed in a future version.
      - `enabled` boolean — Determines if alert notifications should be send for expiring SSL certificates.
      - `alertThreshold` integer — At what moment in time to start alerting on SSL certificates.
    - `runBasedEscalation` AlertSettingsRunBasedEscalation
      - `failedRunThreshold` 1 | 2 | 3 | 4 | 5 — After how many failed consecutive check runs an alert notification should be send.
    - `timeBasedEscalation` AlertSettingsTimeBasedEscalation
      - `minutesFailingThreshold` 5 | 10 | 15 | 30 — After how many minutes after a check starts failing an alert should be send.
    - `parallelRunFailureThreshold` ParallelRunFailureThreshold
      - `enabled` boolean — Determines if parallel run threshold is enabled
      - `percentage` 10 | 20 | 30 | 40 | 50 | 60 | 70 | 80 | 90 | 100 — The percentage of parallel runs that should fail before an alert is triggered
  - `useGlobalAlertSettings` boolean — When true, the account level alert setting will be used, not the alert setting defined on this check.
  - `groupId` number, nullable — The id of the check group this check is part of.
  - `groupOrder` number, nullable — The position of this check in a check group. It determines in what order checks are run when a group is triggered from the API or from CI/CD.
  - `runtimeId` '2026.04' | '2025.04' | '2024.09' | '2024.02' | '2023.09' | '2023.02' | '2022.10', nullable — The runtime version, i.e. fixed set of runtime dependencies, used to execute this check.
  - `alertChannelSubscriptions` Model42[] — List of alert channel subscriptions.
    - `alertChannelId` number, required
    - `activated` boolean, required
  - `retryStrategy` RetryStrategy, nullable — The strategy to determine how failed checks are retried.
    - `type` 'FIXED' | 'LINEAR' | 'EXPONENTIAL' | 'SINGLE_RETRY', required — Determines which type of retry strategy to use.
    - `baseBackoffSeconds` number — The number of seconds to wait before the first retry attempt.
    - `sameRegion` boolean — Whether retries should be run in the same region as the initial check run.
    - `maxRetries` number — The maximum number of attempts to retry the check. Not supported for SINGLE_RETRY
    - `maxDurationSeconds` number — The total amount of time to continue retrying the check. Not supported for SINGLE_RETRY
    - `onlyOn` RetryOnlyOnValue[]
  - `triggerIncident` TriggerIncident, nullable — Determines whether the check or monitor should create and resolve an incident based on its alert configuration. Useful for status page automation.
    - `serviceId` string, required — The status page service that the incident will be associated with.
    - `severity` 'CRITICAL' | 'MAJOR' | 'MEDIUM' | 'MINOR', required — The severity level of the incident.
    - `name` string, required — The name of the incident.
    - `description` string, required — A detailed description of the incident.
    - `notifySubscribers` boolean, required — Whether to notify subscribers when the incident is triggered.
  - `runParallel` boolean — When true, the check will run in parallel in all selected locations.
  - `description` string, nullable — A description of the check.
  - `frequency` 0 | 1 | 2 | 5 | 10 | 15 | 30 | 60 | 120 | 180 | 360 | 720 | 1440 — How often the check should run in minutes.
  - `frequencyOffset` integer — Used for setting seconds for check frequencies under 1 minutes (only for API & TCP checks) and spreading checks over a time range for frequencies over 1 minute. This works as follows: Checks with a frequency of 0 can have a frequencyOffset of 10, 20 or 30 meaning they will run every 10, 20 or 30 seconds. Checks with a frequency lower than and equal to 60 can have a frequencyOffset between 1 and a max value based on the formula "Math.floor(frequency * 10)", i.e. for a check that runs every 5 minutes the max frequencyOffset is 50. Checks with a frequency higher than 60 can have a frequencyOffset between 1 and a max value based on the formula "Math.ceil(frequency / 60)", i.e. for a check that runs every 720 minutes, the max frequencyOffset is 12.
  - `request` IcmpMonitorRequest, required — Determines the request that the ICMP monitor is going to run.
    - `hostname` string, required
    - `ipFamily` 'IPv4' | 'IPv6', nullable
    - `pingCount` integer, nullable
    - `assertions` Model169[] — Check the main Checkly documentation on assertions.
      - `source` 'LATENCY' | 'JSON_RESPONSE'
      - `comparison` string
      - `property` string, required
      - `target` string
      - `regex` string, nullable
  - `heartbeat` Heartbeat, required
  - `script` string, required
  - `scriptPath` string, nullable — Path of the script in the runtime.
  - `sslCheckDomain` string
  - `environmentVariables` EnvironmentVariable[], nullable — Key/value pairs for setting environment variables during check execution. These are only relevant for Browser checks. Use global environment variables whenever possible.
    - `key` string, required — The key of the environment variable (this value cannot be changed).
    - `value` string, required
    - `locked` boolean — Used only in the UI to hide the value like a password.
    - `secret` boolean — Set an environment variable as secret. Once set, its value cannot be unlocked.
  - `setupSnippetId` number, nullable — An ID reference to a snippet to use in the setup phase of an API check.
  - `tearDownSnippetId` number, nullable — An ID reference to a snippet to use in the teardown phase of an API check.
  - `localSetupScript` string, nullable — A valid piece of Node.js code to run in the setup phase.
  - `localTearDownScript` string, nullable — A valid piece of Node.js code to run in the teardown phase.
  - `degradedResponseTime` number, nullable — The response time in milliseconds where a check should be considered degraded.
  - `maxResponseTime` number, nullable — The response time in milliseconds where a check should be considered failing.
  - `degradedPacketLossThreshold` number, nullable — The packet loss percentage threshold for degraded state. Must be greater than 0.
  - `maxPacketLossThreshold` number, nullable — The packet loss percentage threshold for failed state. Must be greater than 0 and greater than or equal to degradedPacketLossThreshold.
  - `privateLocations` string[], nullable — An array of one or more private locations where to run the check.

## Response `201`

Created

- MonitorICMP
  - `id` string
  - `name` string, required — The name of the check.
  - `activated` boolean — Determines if the check is running or not.
  - `muted` boolean — Determines if any notifications will be send out when a check fails and/or recovers.
  - `doubleCheck` boolean — [Deprecated] Retry failed check runs. This property is deprecated, and `retryStrategy` can be used instead.
  - `shouldFail` boolean — Allows to invert the behaviour of when a check is considered to fail. Allows for validating error status like 404.
  - `locations` Model170[], nullable — An array of one or more data center locations where to run this check.
  - `tags` string[] — Tags for organizing and filtering checks.
  - `alertSettings` CheckAlertSettings, nullable — Alert settings.
    - `escalationType` 'RUN_BASED' | 'TIME_BASED' — Determines what type of escalation to use.
    - `reminders` AlertSettingsReminders
      - `amount` 0 | 1 | 2 | 3 | 4 | 5 | 100000 — How many reminders to send out after the initial alert notification.
      - `interval` 1 | 2 | 3 | 4 | 5 | 10 | 15 | 30 — At what interval the reminders should be send.
    - `sslCertificates` AlertSettingsSSLCertificates — [DEPRECATED] `sslCertificates` is deprecated and is not longer used. Please ignore it, will be removed in a future version.
      - `enabled` boolean — Determines if alert notifications should be send for expiring SSL certificates.
      - `alertThreshold` integer — At what moment in time to start alerting on SSL certificates.
    - `runBasedEscalation` AlertSettingsRunBasedEscalation
      - `failedRunThreshold` 1 | 2 | 3 | 4 | 5 — After how many failed consecutive check runs an alert notification should be send.
    - `timeBasedEscalation` AlertSettingsTimeBasedEscalation
      - `minutesFailingThreshold` 5 | 10 | 15 | 30 — After how many minutes after a check starts failing an alert should be send.
    - `parallelRunFailureThreshold` ParallelRunFailureThreshold
      - `enabled` boolean — Determines if parallel run threshold is enabled
      - `percentage` 10 | 20 | 30 | 40 | 50 | 60 | 70 | 80 | 90 | 100 — The percentage of parallel runs that should fail before an alert is triggered
  - `useGlobalAlertSettings` boolean — When true, the account level alert setting will be used, not the alert setting defined on this check.
  - `groupId` number, nullable — The id of the check group this check is part of.
  - `groupOrder` number, nullable — The position of this check in a check group. It determines in what order checks are run when a group is triggered from the API or from CI/CD.
  - `runtimeId` '2026.04' | '2025.04' | '2024.09' | '2024.02' | '2023.09' | '2023.02' | '2022.10', nullable — The runtime version, i.e. fixed set of runtime dependencies, used to execute this check.
  - `alertChannelSubscriptions` CheckAlertChannelSubscription[]
    - `alertChannelId` number, required
    - `activated` boolean, required
  - `retryStrategy` RetryStrategy, nullable — The strategy to determine how failed checks are retried.
    - `type` 'FIXED' | 'LINEAR' | 'EXPONENTIAL' | 'SINGLE_RETRY', required — Determines which type of retry strategy to use.
    - `baseBackoffSeconds` number — The number of seconds to wait before the first retry attempt.
    - `sameRegion` boolean — Whether retries should be run in the same region as the initial check run.
    - `maxRetries` number — The maximum number of attempts to retry the check. Not supported for SINGLE_RETRY
    - `maxDurationSeconds` number — The total amount of time to continue retrying the check. Not supported for SINGLE_RETRY
    - `onlyOn` RetryOnlyOnValue[]
  - `triggerIncident` TriggerIncident, nullable — Determines whether the check or monitor should create and resolve an incident based on its alert configuration. Useful for status page automation.
    - `serviceId` string, required — The status page service that the incident will be associated with.
    - `severity` 'CRITICAL' | 'MAJOR' | 'MEDIUM' | 'MINOR', required — The severity level of the incident.
    - `name` string, required — The name of the incident.
    - `description` string, required — A detailed description of the incident.
    - `notifySubscribers` boolean, required — Whether to notify subscribers when the incident is triggered.
  - `runParallel` boolean — When true, the check will run in parallel in all selected locations.
  - `description` string, nullable — A description of the check.
  - `frequency` 0 | 1 | 2 | 5 | 10 | 15 | 30 | 60 | 120 | 180 | 360 | 720 | 1440 — How often the check should run in minutes.
  - `frequencyOffset` integer — Used for setting seconds for check frequencies under 1 minutes (only for API & TCP checks) and spreading checks over a time range for frequencies over 1 minute. This works as follows: Checks with a frequency of 0 can have a frequencyOffset of 10, 20 or 30 meaning they will run every 10, 20 or 30 seconds. Checks with a frequency lower than and equal to 60 can have a frequencyOffset between 1 and a max value based on the formula "Math.floor(frequency * 10)", i.e. for a check that runs every 5 minutes the max frequencyOffset is 50. Checks with a frequency higher than 60 can have a frequencyOffset between 1 and a max value based on the formula "Math.ceil(frequency / 60)", i.e. for a check that runs every 720 minutes, the max frequencyOffset is 12.
  - `created_at` string, date
  - `updated_at` string, date-time, nullable
  - `alertChannels` CheckAlertChannels, nullable
    - `email` CheckAlertEmail[]
      - `address` string, required
    - `webhook` CheckAlertWebhook[]
      - `name` string
      - `url` string, required
      - `method` 'GET' | 'POST' | 'PUT' | 'HEAD' | 'DELETE' | 'PATCH', nullable
      - `headers` KeyValue[]
        - `key` string, required
        - `value` string, required
        - `locked` boolean
      - `queryParameters` KeyValue[]
        - `key` string, required
        - `value` string, required
        - `locked` boolean
    - `slack` CheckAlertSlack[]
      - `url` string, required
    - `sms` CheckAlertSMS[]
      - `number` string, required
      - `name` string, required
  - `degradedPacketLossThreshold` number, nullable
  - `maxPacketLossThreshold` number, nullable
  - `project` CheckProject, nullable — The project that manages this check, or null when the check is not managed by code.
    - `id` string — The ID of the project that manages this check.
    - `logicalId` string — The logical ID of the managing project, as declared in code.
    - `name` string — The name of the managing project.
  - `logicalId` string, nullable — The check's logical ID within the managing project, or null when it is not managed by code.
  - `member` boolean, nullable — True when the project owns this check, false when it merely references a check owned outside the project. Null when not managed by code.
  - `pending` boolean, nullable — True when the binding is reserved by an import plan that has not been deployed yet. Null when not managed by code.
  - `privateLocations` string[], nullable — An array of one or more private locations where to run the check.
  - `request` Model174 — Determines the request that the ICMP monitor is going to run.
    - `hostname` string, required
    - `ipFamily` 'IPv4' | 'IPv6', nullable
    - `pingCount` integer, nullable
    - `assertions` Model169[] — Check the main Checkly documentation on assertions.
      - `source` 'LATENCY' | 'JSON_RESPONSE'
      - `comparison` string
      - `property` string, required
      - `target` string
      - `regex` string, nullable
  - `checkType` 'ICMP'

## Other responses

- `401` — Unauthorized
- `402` — Payment Required
- `403` — Forbidden
- `429` — Too Many Requests

---

[API](https://skmtc.net/checklyhq/apis/checkly-public-api.md) · [All operations](https://skmtc.net/checklyhq/apis/checkly-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/checklyhq/checkly-public-api/versions/9e903da4f3da/schema)