# 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

1. **Create a check** in a project, or let a job create one automatically on its first ping.
2. **Ping it from the job.** Wrap the command with [checkpulse-run](/docs/cli), or call the ping URL with curl.
3. **Add alert channels**: email, webhooks, Slack, Discord, Teams, Telegram, ntfy, PagerDuty, and [more](/docs/integrations).
4. **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](/docs/agents) or the [REST API](/docs/api) with a project API key. Every page here is also available as Markdown (add `.md` to the URL), and [llms.txt](https://checkpulse.foo/llms.txt) lists them all.

## Pages

- [Pinging](/docs/pinging): URLs, signals, output, run IDs, and automatic check creation.
- [Schedules](/docs/schedules): intervals, cron expressions, time zones, and grace periods.
- [checkpulse-run](/docs/cli): the job wrapper.
- [AI agents](/docs/agents): MCP, API keys, and safe automation.
- [REST API](/docs/api): authentication, errors, and endpoints.
- [Alert channels](/docs/integrations): integrations, payloads, and signatures.
- [Incidents and silences](/docs/incidents): acknowledgements, reminders, badges, and metrics.
- [Self-hosting](/docs/self-hosting): running Checkpulse yourself.