Heartbeat Monitors (Cron Jobs & Scheduled Tasks)

Updated: 2026-06-15

Heartbeat monitors are designed for work that runs on a schedule (cron jobs, background workers, backups, sync tasks). Instead of us checking an endpoint, your job pings us. If we don’t receive a ping within the expected interval + grace period, we alert you.

When to use heartbeats

Use heartbeat monitors for:

Cron jobs (nightly backups, reports)
Scheduled tasks (queues, workers)
ETL/data syncs
Any job that should run regularly and “phone home”

If you need to monitor a website/API uptime, use regular monitors instead.

How it works

Create a heartbeat monitor from the heartbeat dashboard. Edit or delete existing monitors via the icons on each row.
Copy its unique ping URL.
Add a curl/HTTP request to your job after it completes successfully.
We mark it healthy when pings arrive on time; missed when they don’t.

Ping URL (public endpoint)

The ping endpoint is intentionally public so cronjobs can call it directly.

GET and POST are supported.
The token is the secret (treat it like a password).

Endpoint:

https://statuspage.me/api/heartbeat/{token}

Simple GET ping

curl -s https://statuspage.me/api/heartbeat/{token} > /dev/null

POST ping with optional metadata

You can attach small JSON metadata (up to ~4KB) for later troubleshooting.

curl -s -X POST https://statuspage.me/api/heartbeat/{token} \
  -H "Content-Type: application/json" \
  -d '{"job":"daily_backup","records":1234,"duration_ms":45678}' > /dev/null

Response

{
  "status": "ok",
  "message": "Ping recorded"
}

If the token is unknown, the endpoint returns 404.

Expected interval & grace period

Each heartbeat has:

Expected interval: how often you expect pings (e.g. every 5 minutes, every 24 hours)
Grace period: extra buffer before marking it missed (default: 5 minutes)

Auto-infer interval (recommended)

If you leave expected interval empty, we’ll auto-infer it from the first few pings. This is ideal when a job is “about every N minutes” but may drift slightly.

Status meanings

Pending: waiting for the first pings
Healthy: receiving pings on time
Missed: no ping within expected interval + grace
Paused: manually disabled

Monitor dashboard

The heartbeat monitor list page (/user/heartbeats) provides real-time visual feedback on all your heartbeat monitors.

Quota usage

A progress bar at the top of the page shows how many heartbeat monitors you’re using against your plan’s limit (e.g., “2 / 15 heartbeats used”). The bar changes color as you approach the limit:

Green — under 60% used
Yellow — 60–85% used
Red — over 85% used (near quota)

If you reach the quota, you’ll need to delete an existing monitor before creating a new one.

Live auto-refresh

Heartbeat rows update in real time — no page reload needed. Every 15 seconds the page polls for fresh data and refreshes:

Status badges — Healthy / Missed / Pending / Paused
Last ping times — relative timestamps with color coding (green when on-time, yellow approaching deadline, red when missed)
Next expected countdown — a live countdown timer showing “in 34s” or “12s overdue” that ticks every second, color-coded green → yellow → red
Delta sparkline — an inline SVG mini-chart showing the last 20 ping deltas (seconds between pings) as a smoothed curve; hover over any data point to see the exact delta value (e.g., “5m 5s”)
Delta bar — a thin progress bar showing elapsed time since the last ping vs. the total deadline (interval + grace), color-coded from green through yellow to red

Refresh pauses automatically when the browser tab is hidden to avoid unnecessary requests.

Editing & deleting

Edit or delete any heartbeat monitor directly from the row:

Edit (pencil icon) — opens a Bootstrap form modal pre-filled with current settings (name, description, interval, grace, visibility, auto-infer). Save changes and the row updates in place without reloading the page.
Delete (trash icon) — opens a confirmation dialog. Deleting permanently removes the monitor and all ping history.

Detail view

Click any heartbeat name to open the detail page (/user/heartbeats/:id), which provides deeper insight into a single monitor.

Delta chart

A time-series area chart (ApexCharts) shows delta_seconds over your last ~100 pings. The chart includes:

A smooth gradient fill showing the trend of ping intervals
A dashed reference line at your expected interval (amber) so you can spot drift at a glance
Hover tooltips with exact delta values and timestamps
If deltas consistently exceed the expected interval by a large margin, the chart area turns red to draw attention

Live pings table

Recent pings appear in a table with relative timestamps, delta values, source IPs, and user agents. The table auto-refreshes every 15 seconds — new pings appear without reloading the page.

Status card

The sidebar status card shows the current countdown (“in 12s” or “45s overdue”), sample count, and basic configuration — all updating in real time.

Alerts & notifications

Heartbeat alerts use your status page’s configured notification channels.

Common workflow:

Get alerted when a heartbeat becomes missed
Get a recovery notification when a ping arrives again

Escalation reminders (still-missed alerts)

If a heartbeat stays missed for an extended period, you’ll receive escalation reminders even without a new ping:

Reminder stage	Fires after
Stage 1	1 hour since first missed
Stage 2	24 hours since first missed

This ensures your team isn’t silently waiting for a recovery that never comes. The reminder stage resets automatically when a ping arrives.

Interval drift alert

Before a heartbeat is fully missed, we track whether each ping is arriving progressively later than expected. If five consecutive pings show a monotonically increasing delta and the latest delta is more than 80% of the expected interval, a heartbeat drift warning fires.

This catches cron jobs or background workers that are degrading — running slower each cycle — before they miss an interval entirely.

The drift alert has a 6-hour cooldown per monitor to avoid repeated noise.

Troubleshooting

Getting 404 Heartbeat not found: the token is wrong, rotated, or belongs to another environment.
Still showing missed even though job runs:
- ensure the ping runs after the job succeeds
- check networking/DNS from the job environment
- confirm the job is hitting the correct base URL for your account/region
Accidental token leak: regenerate the token in the heartbeat settings and update your job.

Security notes

The ping endpoint is public by design.
The token is high-entropy and should be kept secret.
Avoid logging the full ping URL in CI/CD output.
Rotate/regenerate tokens if you suspect exposure.

StatusPage.me Help Center