Documentation

Check statuses & lifecycle

A heartbeat check has five statuses. Understanding the transitions explains exactly when an alert arrives — and why sometimes it (correctly) doesn't.

Status	Meaning	Alerts
new	the check exists, no ping has arrived yet	none
up	pings arrive on time	the up event on recovery
late	the deadline was missed, the grace period is running	the late event (if enabled)
down	grace expired, or the job explicitly reported failure	the down event + reminders
paused	monitoring switched off manually	none

Why new never alerts

A check in the new status is not tracked by the scheduler: it has no deadline yet — one appears only with the first ping. So you can create checks for future jobs in advance (or roll the config out with a deploy): until the code ships and pings, there are no false downs. The first successful ping flips the check to up and sets the first deadline.

The deadline: period and cron

The deadline is the moment the next ping is due. It is computed from the actual time of the last ping:

• period — last ping + period_sec. The schedule "floats": a job that starts with drift does not accumulate error;
• cron — the next run of the cron expression in the check's timezone after the last ping. DST transitions are handled by the timezone;
• OnCalendar — like cron, using a systemd expression.

Grace

Grace is the allowance after the deadline — insurance against schedule jitter and long runs: cron rarely fires to the second. At the deadline the check becomes late ("running behind, not an incident yet"), and only grace_sec seconds later — down:

up ──(deadline)──▶ late ──(+ grace)──▶ down
 ▲                                       │
 └────────── any successful ping ◀───────┘

Grace is set per check: 0 to 30 days. Time-based transitions are executed by the scheduler with minute precision.

Instant down

An explicit failure signal bypasses grace: a ping to /<uuid>/fail or with a non-zero exit code (/<uuid>/42) flips the check to down immediately — the job itself said it failed, there is nothing to wait for.

Recovery, pause and reset

• from late and down the check returns to up with the very next successful ping — the "up" alert goes out and reminders stop;
• paused — a manual pause: pings don't change the status, deadlines aren't tracked, no alerts. For HTTP checks paused means "don't probe";
• reset (the "Reset" button on the check page) returns the check to new, as if it had just been created: the last ping, duration and deadline are cleared. The ping and flip history is kept — the reset itself shows up in the timeline as its own event. Counting starts over with the first ping; handy after a long idle spell or when a job moves.

Pause, resume, delete and tag assignment also work in bulk — tick the checkboxes in the list. From the check page you can clone a check (config without history) and move it to another project of the account.

Statuses are visible on the dashboard, in the API and on public badges; HTTP checks use K confirmations instead of ping timing.