Heartbeat Monitor Reference

A heartbeat monitor watches jobs that run on their own schedule: cron jobs, queue workers, backups, ETL pipelines. openstatus never calls your job. Instead, your job sends a request to a unique ping URL every time it runs, and the monitor goes down when a ping does not arrive in time or when the job reports a failure.

Use cases:

• Nightly backups and database dumps.
• Scheduled scripts on a server, in Kubernetes CronJobs or in CI.
• Background workers that should report in at a steady pace.

How it works

1. Create a heartbeat monitor and set how often your job runs (period) and how late a ping may be (grace period).
2. Add a request to the ping URL at the end of your job.
3. Every ping moves the deadline to last ping + period + grace.
4. If the deadline passes without a ping, the monitor goes down, an incident opens and your notification channels are alerted. The next ping recovers it and resolves the incident.
5. If your job pings its URL followed by /fail, the monitor goes down the same way. The next ping to the plain URL recovers it.

Deadlines and failures are checked every minute, so an alert can arrive up to a minute later.

Configuration

Period

Type: Duration (required) Range: 1 minute to 30 days

How often your job is expected to ping, for example 1 hour for an hourly cron job.

Grace period

Type: Duration (required) Range: 1 minute to 7 days

Extra time after the period before a late ping counts as missed. Set it to cover how long your job runs plus any start-up delay.

Sending pings

The ping URL looks like https://api.openstatus.dev/heartbeat/<token>. It accepts GET, POST and HEAD requests and needs no authentication: the token in the URL identifies the monitor, so keep it secret. You can regenerate it from the monitor settings, after which the old URL stops working.

The examples below use the hosted URL. Copy the exact ping URL shown in your monitor: a self-hosted instance uses its own base URL.

# at the end of a script
curl -fsS -m 10 --retry 3 https://api.openstatus.dev/heartbeat/<token>

# crontab: ping only when the job succeeds
0 * * * * /path/to/job.sh && curl -fsS -m 10 --retry 3 https://api.openstatus.dev/heartbeat/<token>

Reporting failures

Add /fail to the ping URL to report that the job failed. The monitor goes down within a minute instead of waiting for the grace period, and the alert says the job reported a failure. A fail also counts as hearing from the job: the deadline moves forward as with a normal ping, so a job that keeps failing alerts once and stays down until it succeeds again.

# ping on success, report the failure otherwise
/path/to/job.sh && curl -fsS -m 10 --retry 3 https://api.openstatus.dev/heartbeat/<token> \
  || curl -fsS -m 10 --retry 3 https://api.openstatus.dev/heartbeat/<token>/fail

Send the job's error output as a POST body to keep it with the failed ping:

/path/to/job.sh 2> /tmp/job.err \
  || curl -fsS -m 10 --retry 3 --data-binary @/tmp/job.err https://api.openstatus.dev/heartbeat/<token>/fail

The body is never included in alerts. It stays in the monitor's Logs tab.

If you would rather not report failures, simply do not ping: the monitor goes down once the grace period runs out.

Responses

What is stored

Each ping is kept with its time, whether it reported a failure, the client IP, the HTTP method and user agent, the request headers and, for POST requests, the first 10 KB of the body. Headers that look like credentials (Authorization, Cookie, or any name containing token, secret, key, password or signature) are redacted before they are stored, and so are values that look like secrets in the body (bearer tokens, JWTs, token=… pairs, JSON fields such as api_key). Body redaction matches known patterns only, so do not send secrets in the body. You can see each ping in the monitor's Logs tab, which is a handy place to send the tail of your job's output.

Ping details are only visible to members of your workspace. They never appear on status pages.

Status pages

A heartbeat monitor can be added to a status page like any other monitor. Its bar shows the days on which pings were received, in red when the job reported a failure that day, and its uptime is computed from the incidents opened by missed pings and reported failures.

Related resources

• Create your first monitor — step-by-step tutorial on setting up a monitor.
• Notification Channels Reference — where heartbeat alerts are sent.