Heartbeat Monitoring Guide

Heartbeat monitoring tracks a device or a piece of software by sending regular heartbeat events to a remote monitoring service. Cronitor alerts you when:

• The heartbeats stop.
• The rhythm of the heartbeats changes.
• Data sent with the heartbeat fails an assertion you defined.

Creating a monitor and sending pings is covered in Heartbeat monitoring. This page is the shorter concept guide.

A heartbeat monitor, with recent ticks and the metric assertions for that host.

Creating Heartbeat Monitors

You can create a heartbeat in the app, with the Monitor API, or from a YAML file.

The Python SDK reads a YAML file with top-level jobs, checks, and heartbeats keys. This heartbeat expects a ping every 60 seconds and fails the assertion when error_count is 3 or higher:

heartbeats:
  airflow-heartbeat:
    schedule: every 60 seconds
    assertions:
      - metric.error_count < 3
    notify:
      - devops-alerts

schedule also accepts a cron expression or a time of day such as at 14:30. API version 2025-11-28 uses a schedules array instead of the schedule string. Requests on the default API version still use schedule. See the Monitor API.

Set CRONITOR_API_KEY to the SDK Integration key before the process starts. The package reads that variable on import. Then apply the file:

import cronitor
cronitor.config = './cronitor.yaml'
cronitor.apply_config()

The cronitor-python README documents the YAML file. Other languages are listed under SDKs.

Sending Heartbeat Events

A new monitor stays inactive, and alerts are not sent, until the first heartbeat. Send events with the Telemetry API. A request with no state parameter records a tick:

curl --fail --get "https://cronitor.link/p/YOUR_TELEMETRY_KEY/airflow-heartbeat" \
  --data-urlencode "metric=error_count:1"

Replace YOUR_TELEMETRY_KEY with a key from API settings that has monitor:telemetry permission. A telemetry key can only send events. An SDK Integration key has that permission too, so it also works in a /p/ URL. You can also copy the telemetry URL from the monitor page.

If the host cannot open a connection to cronitor.link, send the ping through a proxy. See Monitoring Private Servers.

Alert Settings

Cronitor can alert by email, Slack, PagerDuty, Microsoft Teams, SMS, webhooks, and other integrations.

A notification list is a set of those channels attached to a monitor. When the monitor fails or recovers, every channel on the list is notified. Create or edit a list on the alerts settings page.

Tip: A new account gets a list named "Default" with your email on it. If you do not name a list, Cronitor uses that one.

FAQs

• If anonymous events are disabled on the API settings page, every ping needs a telemetry key. Put the key in the /p/YOUR_TELEMETRY_KEY/monitor-key path, or pass &auth_key= on a code-only URL. With CronitorCLI, set CRONITOR_PING_API_KEY. The --ping-api-key flag still works, but the value then sits in your shell history. Prefer the environment variable. See Using Cronitor CLI.
• Give the ping a timeout and a few retries so a slow network does not hang the caller or drop the event: curl -fsS -m 10 --retry 3 "https://cronitor.link/p/YOUR_TELEMETRY_KEY/airflow-heartbeat".
• Use HTTPS. Unencrypted HTTP pings are accepted only on cronitor.link. HTTP requests to cronitor.io are redirected to HTTPS.
• Alerts start after the first ping. Until then the monitor is not initialized.
• Ping URLs accept GET, POST, and HEAD. A POST body is discarded. Send state, metric, and message as query parameters.
• Job lifecycle paths can be shortened to /r, /c, and /f. A heartbeat is a request with no state, which records a tick. /t is the short form of tick.