Heartbeat Monitors (Cron Jobs & Scheduled Tasks)

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

1. Create a heartbeat monitor in the dashboard.
2. Copy its unique ping URL.
3. Add a curl/HTTP request to your job after it completes successfully.
4. 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

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

See also:

• Monitoring alerts: /docs/monitoring/monitoring-alerts

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 (prod vs localhost)
• 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.