Documentation — CronBeacon

Quick Start

Integrate CronBeacon in 5 minutes.

Create an account on cronbeacon.com
Generate an API token in the Tokens tab
Add the bash wrapper to your cron jobs (or a simple curl)
Configure the schedule for each job to enable missed run detection

Key Concepts

Job

A job represents a scheduled task to monitor (cron, ETL, backup, worker...). You define its expected schedule and CronBeacon checks that it runs correctly.

Run

A run is a single execution of a job. Each event received (started, succeeded, failed) creates an immutable run with timestamp, duration, and metadata.

Alert

An alert is triggered when a job misses its schedule (missed), fails (failing), or degrades. Alerts are sent via email, Slack, or webhook based on your configured channels.

State

A job's state is continuously computed: on_time, late, degraded, missed, failing. The reliability score (7d / 30d) gives a long-term view of each job's health.

Job States

State	Meaning
on_time	Last run succeeded within the expected timeframe.
late	Run succeeded but after the grace period.
degraded	Job is running but with anomalies (excessive duration, partial errors).
missed	No run received within the expected timeframe. The job probably didn't execute.
failing	Last run failed (event: failed).

State

Meaning

on_time

Last run succeeded within the expected timeframe.

late

Run succeeded but after the grace period.

degraded

Job is running but with anomalies (excessive duration, partial errors).

missed

No run received within the expected timeframe. The job probably didn't execute.

failing

Last run failed (event: failed).

Integration

Bash wrapper

#!/bin/bash CB_TOKEN="cb_your_token" CB_URL="https://cronbeacon.com/api/v1/ingest/events" CB_JOB="my_job_key" START=$(date +%s%3N) /path/to/your_script.sh EXIT_CODE=$? DURATION=$(( $(date +%s%3N) - START )) if [ $EXIT_CODE -eq 0 ]; then EVENT="succeeded"; MSG="ok" else EVENT="failed"; MSG="exit code $EXIT_CODE" fi curl -s -X POST "$CB_URL" \ -H "Authorization: Bearer $CB_TOKEN" \ -H "Content-Type: application/json" \ -d "{\"job_key\":\"$CB_JOB\",\"event\":\"$EVENT\",\"duration_ms\":$DURATION,\"message\":\"$MSG\"}"

curl — Single event

curl -X POST https://cronbeacon.com/api/v1/ingest/events \ -H "Authorization: Bearer cb_your_token" \ -H "Content-Type: application/json" \ -d '{"job_key":"nightly_backup","event":"succeeded","duration_ms":4200}'

PHP

$ch = curl_init('https://cronbeacon.com/api/v1/ingest/events'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer cb_your_token', 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode([ 'job_key' => 'nightly_backup', 'event' => 'succeeded', 'duration_ms' => 4200, ]), CURLOPT_RETURNTRANSFER => true, ]); $response = curl_exec($ch); curl_close($ch);