Heartbeat Monitors

Heartbeat monitors are passive monitors. Instead of Unseenr checking your service, your service sends periodic pings to Unseenr. If a ping is missed within the expected interval plus grace period, the monitor is marked as DOWN.

Use Cases

• Cron jobs: Verify scheduled tasks ran successfully
• Background workers: Ensure worker processes are alive
• Batch jobs: Confirm data processing completed
• Server health: Periodic self-reporting from servers

How It Works

1. Create a heartbeat monitor in your project
2. Unseenr generates a unique heartbeat token
3. Your service sends HTTP requests to https://uptime.unseenr.io/{token}
4. If no ping arrives within the interval + grace period, the monitor goes DOWN

Ping Types (CheckIn Kinds)

Using START + FINISH pairs lets you track job duration and detect jobs that started but never completed.

Configuration

Sending Pings

Simple Ping (curl)

# Simple heartbeat
curl -s https://uptime.unseenr.io/YOUR_TOKEN

# With run ID for tracking specific job runs
curl -s "https://uptime.unseenr.io/YOUR_TOKEN?kind=start&runId=job-123"
# ... job runs ...
curl -s "https://uptime.unseenr.io/YOUR_TOKEN?kind=finish&runId=job-123"

From a Cron Job

# Add to crontab
*/5 * * * * curl -fsS --retry 3 https://uptime.unseenr.io/YOUR_TOKEN > /dev/null

From Node.js

// At the end of your background job
await fetch("https://uptime.unseenr.io/YOUR_TOKEN");

Rate Limiting

Heartbeat pings are rate-limited to 5 pings per second per token. This prevents accidental flooding from misconfigured services.

Check-In History

Each heartbeat monitor tracks its check-in history. You can view:

• Timestamp of each ping
• Kind (PING, START, FINISH)
• Status (OK, ERROR, MISSED)
• Duration (for START/FINISH pairs)
• Request body (if sent)