Heartbeat (Cron Job) Monitors

What a Heartbeat Monitor Is

A Heartbeat monitor is a passive dead man's switch for work that is supposed to run on a schedule: cron jobs, nightly backups, ETL pipelines, queue workers, and similar background tasks. Instead of LoadFocus calling your service, your job calls LoadFocus every time it finishes successfully. If the expected ping does not arrive in time, the monitor goes DOWN and alerts fire.

Unlike active checks, a Heartbeat monitor does not probe anything and has no regions. It simply waits for your job to report in. That makes it ideal for verifying that scheduled work actually ran, not just that an endpoint is reachable.

How It Works

1. You create a Heartbeat monitor and set how often your job should report, plus a grace period.
2. LoadFocus gives you a unique ping URL.
3. Your job pings that URL on each successful run.
4. If a ping arrives within the expected window, the monitor stays UP.
5. If no ping arrives within the interval + grace period, the monitor goes DOWN and alerts fire. LoadFocus checks for missed pings once a minute, so the alert can take up to about a minute longer than interval + grace.
6. The next successful ping recovers the monitor back to UP.

A new monitor is not marked DOWN until it has received its first ping, so run your job once (or call the URL by hand) after you save.

Create a Heartbeat Monitor

1. Open the New API Check page.
2. Choose the Heartbeat type.
3. Pick the Schedule:
   • Fixed interval: set the Expected ping interval in seconds, from 60 to 30 days (for example, 3600 for an hourly job).
   • Cron schedule: enter a Cron expression in UTC (for example, 0 9 * * 1-5 for weekdays at 09:00 UTC).
4. Set a Grace period in seconds, the extra slack you allow before declaring the job late (for example, 300).
5. Choose your alert channels and save the monitor.
6. Copy the Ping URL that LoadFocus shows after saving. It looks like https://apimonitor.loadfocus.com/ping/<token>.

Ping the URL From Your Job

Have your job call the ping URL after it completes successfully. Any HTTP method works, so GET, POST or HEAD are all fine.

The simplest way is to append a curl call to the end of your script or cron entry:

curl -fsS https://apimonitor.loadfocus.com/ping/<your-token>

The -f flag makes curl fail on HTTP errors, -s keeps it quiet, and -S still surfaces real errors. Run this only on success, for example as the last line of the job, so a failed run does not ping and the monitor correctly catches the miss.

The URL itself is the secret: anyone who has it can ping the monitor, so keep it out of public repositories.

Alerts and Recovery

• When interval + grace elapses with no ping, the monitor flips to DOWN and your alert channels are notified.
• When the next ping arrives, the monitor recovers to UP and a recovery notification is sent.

For where the alerts go, see Alert Channels. For active, region-based checks instead, see How to Create a New API Check.