Checkpulse documentation
Checkpulse is a heartbeat monitor for cron jobs, scheduled tasks, backups, and background workers. Each job pings a secret URL when it runs. Checkpulse alerts you when a ping is late, a run fails, or a run takes longer than allowed, and tells you again when the job recovers.
How it works
- Create a check in a project, or let a job create one automatically on its first ping.
- Ping it from the job. Wrap the command with checkpulse-run, or call the ping URL with curl.
- Add alert channels: email, webhooks, Slack, Discord, Teams, Telegram, ntfy, PagerDuty, and more.
- Handle incidents. Acknowledge them, leave notes, and silence alerts during planned work.
Concepts
| Term | Meaning |
|---|---|
| Project | A group of checks with its own members, alert channels, API keys, and ping key. |
| Check | One monitored job: its schedule, grace period, runbook, and secret ping URL. |
| Ping | A request the job sends: start, success, failure, an exit status, or a log message. |
| Grace period | Extra time after the expected ping before alerting. It is also the longest a run may take after a start signal. |
| Incident | Opens when a check goes down and closes when it recovers. People and agents can acknowledge it and add notes. |
| Channel | Where alerts go. Each check chooses its channels. |
| Silence | A time-limited pause of alerts while monitoring continues. |
Check statuses
| Status | Meaning |
|---|---|
| new | Created but not pinged yet. New checks never alert. |
| up | The last ping was a success and the next one is not due. |
| running | A start signal arrived and the run is still within its grace period. |
| late | The expected ping is overdue but still within the grace period. |
| down | The grace period ran out, or the job reported a failure. An alert was sent. |
| paused | Monitoring is stopped. Pings are still recorded. |
Free accounts
Free accounts include 3 projects, 20 checks, 5 alert channels and 3 members per project, 50 email alerts per 30 days, a 1-minute shortest interval, 100 history events per check, and 5 API keys per project. Limits count against the account that created each project. The administrator can raise them.
For AI agents
Agents can do everything through the MCP server or the REST API with a project API key. Every page here is also available as Markdown (add .md to the URL), and llms.txt lists them all.
Pages
- Pinging: URLs, signals, output, run IDs, and automatic check creation.
- Schedules: intervals, cron expressions, time zones, and grace periods.
- checkpulse-run: the job wrapper.
- AI agents: MCP, API keys, and safe automation.
- REST API: authentication, errors, and endpoints.
- Alert channels: integrations, payloads, and signatures.
- Incidents and silences: acknowledgements, reminders, badges, and metrics.
- Self-hosting: running Checkpulse yourself.