CronPulse Docs

Back to site

How CronPulse Works

CronPulse lets you register a monitor for any scheduled job (cron, worker, background task). Each monitor has a required interval (in minutes). Your job must ping the monitor before its interval elapses.

Important: A monitor will not generate "missed" alerts until its first successful ping has been received. This prevents false positives right after creation or deployment.

Typical lifecycle: create monitor → run your job and ping at the end (or start) → receive alerts only if future pings are late or stop. You can optionally set an expires_at timestamp to automatically silence a monitor past a date.

Using raw HTTP (curl)

curl -X POST https://cronpulse.dev/api/monitors \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "nightly-etl",
    "interval": 15,
    "email_recipient": "you@example.com",
    "expires_at": "2030-01-01T00:00:00Z"
  }'
# Response contains the new monitor id
# Suppose the monitor id is 42
curl -X POST https://cronpulse.dev/api/ping/42 \
  -H "Authorization: Bearer YOUR_API_KEY" 
# or GET /api/ping/42
curl -X DELETE https://cronpulse.dev/api/monitors/42 \
  -H "Authorization: Bearer YOUR_API_KEY"

Using the Python client

from cronpulse_lib import CronPulse
from datetime import datetime, UTC, timedelta
import time

api_key = "YOUR_API_KEY"
client = CronPulse(api_key=api_key)

monitor = client.create_monitor(
    name="client generated monitor",
    interval=1,  # minutes
    email="you@example.com",
    expires_at=datetime.now(UTC) + timedelta(days=1),
)

for _ in range(5):
    monitor.ping()
    time.sleep(60)  # simulate work between pings

monitor.delete()

Alert Behavior