Heartbeat Monitoring API Documentation

Learn how to send heartbeats from your cron jobs and scheduled tasks

Base URL

https://api.watchflow.io/heartbeat

Authentication

You can authenticate using your API Key in two ways. The workspace is automatically resolved from your API key.

Option 1: Header (recommended for POST requests)
x-api-key: wf_live_abc123xyz...
Option 2: Query Parameter (perfect for GET one-liners)
?api_key=wf_live_abc123xyz...

💡 No headers needed! Perfect for simple cron jobs and quick tests.

Zero-Config Monitor Creation

No manual setup required! Simply send a ping request with your monitor key and interval, and watchflow will automatically create the monitor for you.

This means you can start monitoring your cron jobs immediately without any configuration. Just add a single curl command to your script, and you're done. The monitor will be created on the first ping and will start tracking your job's health automatically.

Example: Auto-create a monitor with a single request

curl "https://api.watchflow.io/heartbeat/ping?key=my-job&api_key=wf_live_abc123xyz..."

Job Status Types

⟳RunningJob is currently running (set via /ping/start)
✓SuccessJob completed successfully (set via /ping)
✗FailedJob failed explicitly (set via /ping/fail)
â—‹MissedJob didn't run within expected interval (automatically detected)

API Endpoints

/pingPOSTGET

Mark job as successful (supports GET for one-liners)

/ping/startPOST

Start job tracking (for duration measurement)

/ping/failPOST

Mark job as failed with error message

Request Parameters

keyrequired

Unique identifier for your monitor (e.g., "daily-backup", "email-sender")

intervaloptional

Expected heartbeat interval (e.g., "5m", "1h", "24h", "7d"). Default: 24h

nameoptional

Human-readable name for your monitor

dataoptional

Custom metrics or metadata (JSON object)

erroroptional(only for /ping/fail)

Error message describing why the job failed

Code Examples

Simple GET (One-Liner) - No Headers Needed! 🚀

💡 Use api_key as query parameter - perfect for cron jobs where setting headers is difficult!

POST Success (with data)

Start/Fail Pattern (with Duration Tracking)

Bash Wrapper Script

Python with Error Handling

Node.js

Response

Success (200)