Skip to main content
Heartbeat monitors work the other way round from other monitor types: your job pings UptimeIO, and UptimeIO alerts you when a ping does not arrive on time. Use them for anything that runs on a schedule.

When to use it

  • Cron jobs and scheduled tasks
  • Backups
  • ETL and data-sync pipelines
  • Batch jobs and queue workers that should report in regularly

Create a heartbeat monitor

1

Create the monitor

Choose the Heartbeat type and enter a Monitor Name. In Heartbeat Configuration, set the Expected Interval (how often your job runs) and the Grace Period (how much lateness to tolerate).
2

Copy the heartbeat URL

UptimeIO generates a unique Heartbeat Endpoint for the monitor:
3

Ping it from your job

Request the URL when the job finishes successfully.

Settings

Preset values:
  • Expected Interval: 1, 5, 10, 15 and 30 minutes, and 1, 6, 12 and 24 hours. Only presets at or above your plan’s shortest interval are listed.
  • Grace Period: 1 second, 30 seconds, 1, 2, 5, 10, 15 and 30 minutes, and 1, 2, 6, 12 and 24 hours.
The form shows the total time before an alert: the interval plus the grace period. There are no probe locations to choose, because UptimeIO waits for your job instead of checking out.

Example

  • Monitor Name: Nightly backup
  • Expected Interval: 24 hours
  • Grace Period: 30 minutes

Sending a heartbeat

The heartbeat URL needs no authentication: the token in the URL is the credential. Send GET or POST:

Metadata (POST only)

You can attach an optional metadata object to a POST ping, for example how long the job took:
  • Up to 10 keys; keys use letters, digits, _ and -
  • Values are strings (up to 500 characters), numbers or booleans
  • About 2 KB in total
Pings with invalid metadata are rejected. A body that is not valid JSON is ignored and the ping is still recorded.

Rate limits

Pings over the limit are rejected with a 429 response. A monitor rarely needs more than one ping per interval.

Track runs and report failures

Two optional URLs sit next to the heartbeat URL. They are shown on the monitor page after you create it. Both accept GET or POST. /fail also accepts the same optional metadata body as a normal ping. The normal heartbeat URL and /fail accept two optional query parameters: If you call /start and leave out duration_ms, UptimeIO works out the duration from the start call. A value that is not an integer is rejected with a 400 response and nothing is recorded.
Exit codes and durations appear on each event in the monitor’s Recent Heartbeats list. A failure report shows as Failed. The incident reads “Job Reported Failure” and the alert says the job reported failure, rather than that a heartbeat went missing. A failed run resolves like a missed heartbeat: after 3 consecutive on-time pings. /start calls have their own rate limit, so calling /start and then pinging does not trip the limits above.

When incidents open and close

  • Open: no ping arrives within the expected interval plus the grace period. Overdue monitors are checked every 30 seconds. With an interval of 1 hour and a grace period of 5 minutes, the incident opens after 65 minutes of silence. A call to the /fail URL opens one immediately.
  • Resolve: after 3 consecutive on-time pings, which avoids false recoveries from an unstable job.

Integration examples

Best practices

  • Ping only on success, so a failing job stops the pings and opens an incident. To be told the moment a run fails (with its exit code), call /fail instead of staying silent.
  • Match the interval to your schedule: hourly cron = 3,600 seconds, daily backup = 86,400.
  • Size the grace period to the job’s runtime variation: a backup that takes 10 to 20 minutes needs about 30 minutes.
  • Treat the URL as a secret. Anyone with it can send pings and hide real failures.

Troubleshooting

The ping may have failed or gone to the wrong URL, or it was sent before the job finished. Use curl -fsS so errors are visible, confirm the URL, and ping at the end of the job.
The job pings even on failure. Ping only after a successful run (check the exit code), or call the /fail URL when it fails to open an incident immediately.
You are pinging more often than 3 times per 30 seconds (or, on Free, more than once per 120 seconds). Reduce the frequency.
No monitor uses this token. The monitor may have been deleted or its token replaced. Copy the current URL from the monitor.
The Expected Interval is below your plan’s shortest interval (5 minutes on Free). See Plans.

Next steps

HTTP Monitoring

Monitor web services and APIs

Notifications

Configure alerts for heartbeat monitors

Get started

Create a heartbeat monitor for your cron jobs

Get alerted when a scheduled job stops checking in. The Free plan includes heartbeat monitors.