Learn more about Heartbeat monitors in the Heartbeat monitor overview.
Use Heartbeat Monitors to track passive monitoring scenarios where external services ping Checkly at regular intervals. The examples below show how to configure monitoring for different types of scheduled jobs and services.
Before creating heartbeat monitors, ensure you have:
  • An initialized Checkly CLI project
  • External services, cron jobs, or scripts that can send HTTP POST requests
  • Understanding of your scheduled job intervals and expected timing
  • Network access from your services to Checkly’s ping endpoints
For additional setup information, see CLI overview.
import { HeartbeatMonitor } from "checkly/constructs"

new HeartbeatMonitor("daily-backup-heartbeat", {
  name: "Daily Backup Job",
  period: 1,
  periodUnit: "days",
  grace: 2,
  graceUnit: "hours",
})

​
Configuration

The Heartbeat Monitoring configuration consists of specific heartbeat monitoring options and inherited general monitoring options.
ParameterTypeRequiredDefaultDescription
periodnumber✅-The expected period between pings (30 seconds to 365 days)
periodUnitstring✅-Time unit: 'seconds' | 'minutes' | 'hours' | 'days'
gracenumber✅-Grace period before alerting (0 seconds to 365 days)
graceUnitstring✅-Grace time unit: 'seconds' | 'minutes' | 'hours' | 'days'

​
HeartbeatMonitor Options

​
period
number
required
The expected period between pings from your external service. This defines how often your job or service should check in.Usage:
new HeartbeatMonitor('my-heartbeat', {
  name: "My heartbeat",
  period: 1,
  periodUnit: 'days' // Daily check-in expected
  /* More options ... */
})
Examples:
// Daily backup job
new HeartbeatMonitor("backup-job", {
  name: "Daily Database Backup",
  period: 1,
  periodUnit: "days",
  grace: 2,
  graceUnit: "hours",
})
Range: 30 seconds to 365 days
​
periodUnit
string
required
The time unit for the period. Defines whether the period is in seconds, minutes, hours, or days.Usage:
new HeartbeatMonitor("my-heartbeat", {
  name: "My heartbeat",
  period: 2,
  periodUnit: "hours" // Every 2 hours
  /* More options ... */
})
Available units: 'seconds', 'minutes', 'hours', 'days'
​
grace
number
required
The grace period to wait before alerting after the expected ping time has passed. This allows for slight delays in job execution.Usage:
new HeartbeatMonitor('my-heartbeat', {
  period: 1,
  periodUnit: 'hours',
  grace: 10,
  graceUnit: 'minutes' // 10 minute grace period
})
Examples:
// Strict timing requirements
new HeartbeatMonitor("critical-task", {
  name: "Critical System Task",
  period: 5,
  periodUnit: "minutes",
  grace: 1, // Only 1 minute grace
  graceUnit: "minutes",
})
Range: 0 seconds to 365 days
​
graceUnit
string
required
The time unit for the grace period. Defines whether the grace period is in seconds, minutes, hours, or days.Usage:
new HeartbeatMonitor('my-heartbeat', {
  period: 6,
  periodUnit: 'hours',
  grace: 30,
  graceUnit: 'minutes' // 30 minute grace period
})
Available units: 'seconds', 'minutes', 'hours', 'days'

​
General Monitor Options

​
name
string
required
Friendly name for your heartbeat monitor that will be displayed in the Checkly dashboard and used in notifications.Usage:
new HeartbeatMonitor('my-heartbeat', {
  name: 'Daily Backup Job Monitor',
  /* More options ... */
})

​
Examples

new HeartbeatMonitor("backup-job-heartbeat", {
  name: "Daily Database Backup",
  period: 1,
  periodUnit: "days",
  grace: 2,
  graceUnit: "hours",
  tags: ["backup", "database", "critical"],
})

// Example cron job that would ping this heartbeat:
// 0 2 * * * /scripts/backup-database.sh && curl -X POST https://ping.checklyhq.com/[heartbeat-id]

​
Getting the heartbeat Ping URL

After deploying your heartbeat monitor, you can obtain the ping URL in several ways: 
npx checkly deploy

# Output will include:
# Ping URL of heartbeat check "[YOUR_HEARTBEAT_MONITOR_NAME]" is https://ping.checklyhq.com/...
The ping URL is unique for each heartbeat monitor and should be kept secure. Anyone with access to this URL can send pings to your monitor.
Heartbeat monitors are passive - they wait for your external services to ping them. Make sure your jobs and services are configured to send HTTP POST requests to the ping URL on successful completion.