# monitor.heartbeat-check
A heartbeat (a cron job that pings the monitor on a schedule, judged by
`monitor.heartbeat`) as one check behind a status page component, so the
job can sit on the same page as the HTTP targets and feed
`monitor.component-state`, `monitor.incidents` and `monitor.uptime`.
| heartbeat state | check status | why |
| --- | --- | --- |
| `up` | `up` | pinged within its period |
| `late` | `degraded` | past due but inside the grace time: something is slow, nothing has failed yet |
| `down` | `down` | past the grace time: the job has stopped |
| `new` | null | it has never pinged, so there is nothing to report |
## Why this shape
- **Late is not down.** The grace time exists because jobs run long; calling
a late job down would page for exactly the case the grace time was set to
absorb. healthchecks.io, which named these states, only alerts on down.
- **New is null, not up.** A heartbeat that has never pinged has proved
nothing. Calling it up would show a never-deployed job as healthy on the
status page; calling it down would page for a job that is not due yet. The
caller leaves it out of the component's checks (and shows "awaiting first
ping") until the first ping arrives.
## Errors
- `unknown heartbeat state: X`, for anything but `new`, `up`, `late` and
`down` (case-sensitive; a `CheckStatus` such as `degraded` is refused).
## Sources
- healthchecks.io, "Configuring checks: period and grace time" (new, up,
late, down; notifications only when a check goes down):
https://healthchecks.io/docs/configuring_checks/