How to monitor a cron job with a heartbeat

A cron job monitor works the other way round from a website check: your job calls a URL each time it runs. If the call doesn’t arrive on time, you get an alert. Use it for backups, nightly imports, queue workers and anything else that runs without anyone watching.

Create the cron job monitor

1. Open Monitors, choose the Cron jobs filter and then New cron job.
2. Under The job runs, choose On an interval or On a cron schedule.
3. For a cron schedule, enter the Cron expression from your crontab, such as 0 3 * * *, and the Time zone the server’s crontab runs in. The form shows the next runs as you type, and daylight saving is followed.
4. Set the Grace period: how late the ping may be before we alert.
5. Optionally set a Maximum run time, to be alerted when a run takes too long.
6. Tick the alert channels and choose Create monitor. Copy the Ping URL from the page that opens.

Call the URL from your job

The simplest setup pings when the job succeeds:

0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 -o /dev/null https://app.uptimecheck.com/api/hb/your-token

Joined with &&, the ping is only sent when the job succeeds. A GET, POST or HEAD request all count.

Run time, exit codes and output

• Call the ping URL with /start added when the job begins. You see how long each run took, and the maximum run time can alert.
• Call it with /fail, or with the exit code such as /1, to report how the run ended. /0 means success.
• POST the job’s output and it is shown with failures and in the alert. We keep 10,000 characters of it, the start and the end, and requests over 64 kB are refused, so send the last part of a long log, as below.

0 3 * * * curl -fsS -m 10 --retry 3 -o /dev/null https://app.uptimecheck.com/api/hb/your-token/start; /usr/local/bin/backup.sh > /tmp/backup.log 2>&1; code=$?; tail -c 60000 /tmp/backup.log | curl -fsS -m 10 --retry 3 --data-binary @- -o /dev/null https://app.uptimecheck.com/api/hb/your-token/$code

The cron job’s page shows both examples with your own ping URL; copy them from there. For Laravel, Kubernetes, GitHub Actions, systemd and Windows, see cron job ping examples. More on cron job monitoring, and how to monitor cron jobs with heartbeats.