Cron Job Monitoring

Every other monitor type on this page works the same way: MonSPHERE reaches out to you on a schedule. Cron Job Monitoring (the heartbeat monitor type) inverts that — you reach out to us. There's no target URL, no region to pick, and it works for a job running behind a firewall or on a machine with no public IP at all, since nothing ever needs to connect in.

How it works

curl -X POST https://api.monsphere.com/api/v1/organizations/{orgId}/monitors \
  -H "X-Api-Key: msph_live_..." -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly Backup",
    "type": "heartbeat",
    "intervalSeconds": 86400,
    "config": { "gracePeriodSeconds": 900 }
  }'

Creating the monitor returns a unique ping URL (/api/v1/ingest/heartbeat/{token}, shown once on the monitor's own detail page with a ready-to-copy curl line). Add a call to it at the end of your script or the last line of your cron job:

# crontab -e
0 2 * * * /opt/scripts/nightly-backup.sh && curl -fsS https://api.monsphere.com/api/v1/ingest/heartbeat/{token}

Both GET and POST work — a bare curl URL with no flags is enough, so the check-in never needs more than one extra shell token at the end of a line you already have.

Run duration

To also see how long each run takes, call the same URL with /start appended when the job begins:

0 2 * * * curl -fsS https://api.monsphere.com/api/v1/ingest/heartbeat/{token}/start && /opt/scripts/nightly-backup.sh && curl -fsS https://api.monsphere.com/api/v1/ingest/heartbeat/{token}

A start ping doesn't count as a check-in — only the closing ping does, so a job that starts but never finishes still alerts. The closing ping that follows a start ping records the run's duration.

Ping history

Every ping is kept on the monitor's detail page — when it arrived, whether it was a start or a closing ping, the run's duration, and the caller's IP address, HTTP method and user agent — for your plan's history retention period. It's the quickest way to tell "the job didn't run" apart from "the job ran but couldn't reach us".

Grace period

intervalSeconds is how often you expect a ping; gracePeriodSeconds (30s by default) is how much lateness is tolerated before it's treated as missed — a nightly job that usually finishes in 2 minutes but occasionally takes 12 shouldn't page anyone over that normal variance. The check only ever fails for silence, never for what the job itself did — Cron Job Monitoring has no concept of the job's own exit code or output, only whether it checked in on time.

How it runs

A heartbeat monitor is passive on MonSPHERE's side: nothing is ever scraped or probed. The worker only compares "time since last ping" against intervalSeconds + gracePeriodSeconds on its own schedule — the same internal scheduler Synthetic, WHOIS, API Transaction, and DNSBL monitors use, not Blackbox Exporter or Prometheus.