Heartbeat Monitoring

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

Create a heartbeat monitor with an expected interval
Your service pings the monitor at regular intervals using your API key
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

Dashboard
CLI

Go to Dashboard > Heartbeat
Click Add Monitor
Name your monitor and set the expected interval
Copy the monitor ID

kodo heartbeats create \
  --name "nightly-backup" \
  --interval 86400 \
  --grace-period 3600

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:

Bash
Node.js
Python

# 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"}'

// Simple ping
await fetch('https://kodostatus.com/api/heartbeat/MONITOR_ID', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.KODO_API_KEY }
});

// With details
await fetch('https://kodostatus.com/api/heartbeat/MONITOR_ID', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.KODO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    status: 'up',
    response_time_ms: Date.now() - startTime,
    message: 'Processed 1,234 records'
  })
});

import requests
import os

headers = {'X-API-Key': os.environ['KODO_API_KEY']}

# Simple ping
requests.post(
    'https://kodostatus.com/api/heartbeat/MONITOR_ID',
    headers=headers
)

# With details
requests.post(
    'https://kodostatus.com/api/heartbeat/MONITOR_ID',
    headers=headers,
    json={
        'status': 'up',
        'response_time_ms': duration_ms,
        'message': f'Processed {count} records'
    }
)

Status Values

The status field in the request body supports:

Value	Description
`up`	Service is healthy (default if omitted)
`down`	Service has failed
`degraded`	Service 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:

Setting	Description
Interval	How often heartbeats are expected
Grace period	Extra 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

Getting Started

Status Management

Monitoring

Alerting

Automation

Notifications

Client Tracking

Integrations

Heartbeat Monitoring

How It Works

Use Cases

Creating a Heartbeat Monitor

Authentication

Sending Heartbeats

Status Values

Crontab Integration

Grace Periods

Reporting Failures

Incident Safeguards

​How It Works

​Use Cases

​Creating a Heartbeat Monitor

​Authentication

​Sending Heartbeats

​Status Values

​Crontab Integration

​Grace Periods

​Reporting Failures

​Incident Safeguards

How It Works

Use Cases

Creating a Heartbeat Monitor

Authentication

Sending Heartbeats

Status Values

Crontab Integration

Grace Periods

Reporting Failures

Incident Safeguards