Skip to main content
Heartbeat monitoring tracks services that can’t be pinged from the outside. Your service sends periodic “heartbeat” signals, and we alert you if they stop.

​
How It Works

  1. Create a heartbeat monitor with an expected interval
  2. Your service pings the monitor at regular intervals using your API key
  3. If we don’t receive a ping within the expected window, we alert you

​
Use Cases

  • Cron jobs - Verify scheduled tasks complete
  • Background workers - Monitor queue processors
  • Batch jobs - Track ETL and data pipelines
  • Internal services - Services behind firewalls

​
Creating a Heartbeat Monitor

  1. Go to Dashboard > Heartbeat
  2. Click Add Monitor
  3. Name your monitor and set the expected interval
  4. Copy the monitor ID

​
Authentication

Heartbeat endpoints require API key authentication via the X-API-Key header or Authorization: Bearer header. You can use either your organization’s API key or a scoped API key with the heartbeat:write scope.

​
Sending Heartbeats

Add a simple HTTP call to your job: 
# At the end of your cron job
curl -X POST "https://kodostatus.com/api/heartbeat/MONITOR_ID" \
  -H "X-API-Key: YOUR_API_KEY"

# With status and metrics
curl -X POST "https://kodostatus.com/api/heartbeat/MONITOR_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "up", "message": "Backup completed"}'

​
Status Values

The status field in the request body supports:
ValueDescription
upService is healthy (default if omitted)
downService has failed
degradedService is running but impaired

​
Crontab Integration

# Crontab entry with heartbeat
0 2 * * * /path/to/backup.sh && curl -fsS -H "X-API-Key: $KODO_API_KEY" https://kodostatus.com/api/heartbeat/MONITOR_ID

​
Grace Periods

Allow some flexibility for job timing:
SettingDescription
IntervalHow often heartbeats are expected
Grace periodExtra time before marking as late
Example: 5-minute interval with 2x grace multiplier means alerts fire after 10 minutes of silence.

​
Reporting Failures

Report when jobs fail: 
if /path/to/job.sh; then
  curl -X POST "https://kodostatus.com/api/heartbeat/MONITOR_ID" \
    -H "X-API-Key: $KODO_API_KEY" \
    -d '{"status": "up"}'
else
  curl -X POST "https://kodostatus.com/api/heartbeat/MONITOR_ID" \
    -H "X-API-Key: $KODO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"status": "down", "message": "Job failed with exit code 1"}'
fi

​
Incident Safeguards

When a heartbeat is missed, the same incident safeguards apply as with uptime monitors:
  • Failure threshold (default: 2 for heartbeats) — must miss this many consecutive beats
  • Cooldown — prevents rapid duplicate incidents
  • Severity override (default: Minor for heartbeats) — configurable per monitor
  • Draft mode and notification batching — configured at the organization level