Docs

Quick start — your first ping

The fastest way to start is to create a check in MrCron, copy its ping URL, and call it from your job. When the ping stops arriving on schedule, MrCron alerts you.

Simple ping after a job runs

curl -fsS -m 10 "https://mrcron.app/api/ping/YOUR_PING_TOKEN"

With start + success signals

curl -fsS -m 10 "https://mrcron.app/api/ping/YOUR_PING_TOKEN/start"
your-job
curl -fsS -m 10 "https://mrcron.app/api/ping/YOUR_PING_TOKEN"

GitHub Actions step

steps:
  - name: Run backup
    run: ./backup.sh

  - name: Ping MrCron
    if: success()
    run: curl -fsS -m 10 "https://mrcron.app/api/ping/YOUR_PING_TOKEN"

Replace YOUR_PING_TOKENwith the token shown on your check's detail page. The token is a 64-character hex string — keep it private.

Cron syntax

MrCron uses standard 5-field cron syntax to define when a check is expected to ping. The fields are: minute, hour, day-of-month, month, day-of-week.

# ┌───── minute (0–59)
# │ ┌───── hour (0–23)
# │ │ ┌───── day of month (1–31)
# │ │ │ ┌───── month (1–12)
# │ │ │ │ ┌───── day of week (0–7, 0 and 7 = Sunday)
# │ │ │ │ │
  * * * * *

0 3 * * *         # Every day at 03:00 UTC
*/15 * * * *      # Every 15 minutes
0 2 * * 1         # Every Monday at 02:00 UTC
0 0 1 * *         # First day of every month at midnight

All schedules are evaluated in UTC. MrCron calculates nextExpectedAt from the last successful ping and the cron expression — a missed ping is detected when that window closes.

Grace period

Grace period is a buffer added to each check window. A job scheduled for 03:00 with a 5-minute grace period won't be marked LATE until 03:05, and won't be MISSED until the full window plus grace has elapsed.

Set grace period when your job's start time is slightly unpredictable — for example, because it's queued behind other tasks, or because the host wakes up a few minutes late. A reasonable default is 5–10% of the job's interval (e.g. 5 minutes for an hourly job, 30 minutes for a daily job).

# An hourly job with 5-minute grace period
# Schedule:  0 * * * *    (runs every hour)
# Grace:     5 min
#
# If the job is scheduled for 14:00:
#   14:00        → window opens
#   14:00–14:05  → HEALTHY (waiting for ping)
#   14:05        → LATE alert fires (ping overdue)
#   14:55        → next window opens, MISSED logged

Health score bands

Each project has a health score from 0–100, recalculated after every sync and check update. The score determines the status badge color shown in the dashboard.

Score starts at 100 and deductions are applied per signal: failed checks, open incidents, consecutive integration failures, and stale sync data each reduce the score by a weighted amount. A project in UNKNOWN status has no checks and no integration data yet.

Sync cadence

MrCron syncs each integration on a 5-minute interval using a background cron job. Every sync cycle pulls a normalized snapshot from the provider's API, stores it locally, and updates the project health score. The source tool remains the system of record — MrCron only stores summaries.

Snapshot retention tiers:

Raw (5-min granularity)    → kept for 7 days
Hourly rollup              → kept for 30 days
Daily rollup               → kept for 1 year

The Last synced timestamp on each integration panel shows when MrCron last successfully fetched data. If this timestamp is more than 30 minutes old, the /api/health endpoint returns 503 — useful as a liveness probe for uptime monitors.

Alert cooldown

Cooldown prevents alert spam when a condition persists. After an alert fires, MrCron won't send another notification for the same rule and check until the cooldown window expires — even if the condition remains active throughout that period.

Cooldown is set per alert rule when you create it (default: 4 hours). When the underlying condition resolves (e.g. a failed check becomes healthy again), MrCron sends a recovery notification and resets the cooldown regardless of how much time is left.

Example timeline with a 4-hour cooldown:

  08:00  Job misses its ping   → MISSED alert fires
  08:30  Job still MISSED      → suppressed (within cooldown)
  09:00  Job still MISSED      → suppressed
  12:01  Job still MISSED      → alert fires again (cooldown expired)
  12:05  Job pings success     → recovery notification sent, cooldown reset