Cron & heartbeat API

Push a heartbeat from your jobs and get alerted when one is missing or fails.

Cron monitors watch scheduled jobs, backups and background tasks. Your job sends a heartbeat to UptimeDuck when it runs; if the next heartbeat does not arrive on time, the monitor goes down with Missing Heartbeat and you are alerted.

1. Create a cron monitor

  1. In panel.uptimeduck.com, open Cron Monitors and choose Add Cron Monitor.
  2. Pick a schedule type:
    • Interval: the expected heartbeat interval, in minutes or hours.
    • Cron Expression: a standard cron expression such as */5 * * * *.
  3. Set the Grace Period in seconds (default 30) to allow for small delays.
  4. Save. The monitor starts paused and the setup screen shows your heartbeat URL. Click I have set this up once your job is sending heartbeats.

2. Heartbeat endpoint

GET  https://api.uptimeduck.com/push/MONITOR_ID
POST https://api.uptimeduck.com/push/MONITOR_ID

MONITOR_ID is the ID of your cron monitor. The Direct URL on the monitor's Heartbeat Setup card already contains it. No API key or request body is needed: GET and POST behave the same.

Query parameterValuesDescription
statusup (default), downUse down to report a failed run right away. Any value other than down counts as up.
msgtext (URL-encoded)Optional message stored with the heartbeat. With status=down it becomes the error shown in the panel.
ResponseMeaning
200 {"status":"ok"}Heartbeat recorded.
404 {"error":"Monitor not found or invalid type"}The ID does not exist or is not a cron monitor.
500 {"error":"Internal Server Error"}Server error; retry later.

3. Examples

curl

curl "https://api.uptimeduck.com/push/MONITOR_ID?status=up&msg=OK"

Report a failure:

curl "https://api.uptimeduck.com/push/MONITOR_ID?status=down&msg=Backup%20failed"

After a command

Send the heartbeat only if the command succeeds (exit code 0):

your_command && curl "https://api.uptimeduck.com/push/MONITOR_ID?status=up&msg=OK"

Send the heartbeat regardless of the exit status:

your_command; curl "https://api.uptimeduck.com/push/MONITOR_ID?status=up&msg=OK"

crontab

Add the heartbeat to the job line with crontab -e. Keep the monitor's schedule in UptimeDuck the same as the crontab schedule.

0 3 * * * /usr/local/bin/backup.sh && curl "https://api.uptimeduck.com/push/MONITOR_ID?status=up&msg=OK"

How missed heartbeats are detected

  • Interval: the monitor goes down when no heartbeat arrives within the interval plus the grace period after the last one.
  • Cron Expression: the monitor goes down when no heartbeat arrives by the next scheduled run after the last heartbeat, plus the grace period.
  • A heartbeat with status=down marks the monitor down immediately.