> For the complete documentation index, see [llms.txt](https://docs.ilert.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ilert.com/alerting/heartbeat-monitoring.md).
# Heartbeat monitoring
Every other alert source in ilert waits for something to go wrong and tell you. A heartbeat monitor inverts that: it expects a **ping** at a fixed interval, and raises an alert when one fails to arrive. Silence is the signal.
That makes it the right tool for anything whose failure mode is *stopping*, rather than complaining — a nightly backup, a cron job, an edge device, a queue consumer, a monitoring stack that would otherwise have nobody watching it. It also needs nothing inbound: a heartbeat only requires the monitored system to make an outbound HTTPS request, so it works from behind a firewall that would block a real check.
A monitor does not notify anyone by itself. When a ping is overdue it creates an alert through the **alert source** you point it at, and that alert source's escalation policy decides who is paged. Several monitors can share one alert source, which is how you give a fleet of them a single set of alerting settings.
{% hint style="info" %}
Every plan includes heartbeat monitors — one on Free, 25 on Pro and above — and more are available as a paid add-on. See [ilert pricing](https://www.ilert.com/pricing) for the current quotas.
{% endhint %}
## Create a heartbeat monitor
{% stepper %}
{% step %}
### Open the monitor list
In the sidebar, go to **Alerting** → **Heartbeat monitors**, then click **Create heartbeat monitor**.
{% endstep %}
{% step %}
### Fill in the form
Five fields. The one that decides who gets paged is Alert source.
| Field | What it does |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Teams** | Which [teams](/users-and-access-management/teams.md) manage the monitor. Optional |
| **Name** | How the monitor appears in the list. This is not the alert summary |
| **Alert source** | The [alert source](/alerting/configure-alerting/alert-sources.md) the overdue alert is created through. Its escalation policy decides who is paged |
| **Interval** | How long silence is allowed to last, in seconds, minutes, or hours. Defaults to 5 minutes |
| **Alert summary** | The summary text of the alert the monitor creates |
| {% endstep %} | |
{% step %}
### Create it and copy the ping address
Click **Create**. Back on the list, click the monitor's row: a panel opens on the right carrying its **Integration URL** and **Integration email**. That URL is what you ping.
{% endstep %}
{% step %}
### Send the first ping
Until the first ping arrives the monitor sits at **Waiting for first ping** and does nothing at all — the interval timer starts on the first ping, not at creation. Send one, and confirm the status turns **Healthy**.
```bash
curl https://beat.ilert.com/api/pings/YOUR_INTEGRATION_KEY
```
{% endstep %}
{% endstepper %}
## Send pings
The integration URL takes the form `https://beat.ilert.com/api/pings/YOUR_INTEGRATION_KEY`, and answers to both `GET` and `POST` — so anything that can make an HTTP request can ping it, including a webhook receiver that only knows how to POST.
Where the monitored system cannot make HTTP requests at all but can still send mail, ping the monitor's **Integration email** instead. See [Email heartbeat example](/alerting/heartbeat-monitoring/email-heartbeat-example.md).
{% hint style="warning" %}
Write the key into the URL literally, or read it from a variable you have actually set — `${YOUR-APIKEY}` is not a placeholder in a shell, it is parameter substitution. Both bash and zsh expand it to the string `APIKEY`, so the request goes to the wrong URL and comes back `400` as though the key were wrong.
{% endhint %}
### Attach a message to a ping
Add a `message` query parameter and the text is shown as **Last message** in the monitor's details, which is a cheap way to carry the last run's outcome alongside the fact that it ran:
```bash
curl "https://beat.ilert.com/api/pings/YOUR_INTEGRATION_KEY?message=backup+ok+412MB"
```
More recipes are in [CLI heartbeat examples](/alerting/heartbeat-monitoring/cli-heartbeat-examples.md) and the [Prometheus heartbeat example](/alerting/heartbeat-monitoring/prometheus-heartbeat-example.md).
## Watch a monitor
Click any row in **Heartbeat monitors** to open its details panel. Alongside the settings it shows:
| Field | What it tells you |
| ------------------------------------------- | ------------------------------------------------------- |
| **Status** | **Healthy**, **Expired**, or **Waiting for first ping** |
| **Last ping received** | When the last ping arrived |
| **Ping expected until** | The deadline the next ping has to beat |
| **Last message** | The text from the most recent `?message=` ping |
| **Integration URL** / **Integration email** | The two addresses that count as a ping |
The panel also offers **Export to Terraform**, which emits the monitor as a resource block you can check in.
To change a monitor, click the **pencil** icon on its row; the **bin** icon deletes it.
## Alerting settings live on the alert source
A monitor decides *when* an alert is raised. Everything about how that alert behaves — the escalation policy, priority, grouping, auto-resolution — belongs to the alert source it points at, and is configured there: **Alerting** → **Alert sources**, then the source itself.
This is deliberate. Point twenty monitors at one heartbeat alert source and they share one escalation policy and one set of grouping rules, so a datacenter losing power raises one grouped alert rather than twenty.
## Legacy heartbeat alert sources
Before heartbeat monitors, a heartbeat was an alert source of type **Heartbeat**, with its interval fixed to a handful of preset values and one heartbeat per source. Those still work — their ping URL is shown on the alert source itself and has the form `https://api.ilert.com/api/heartbeats/YOUR_INTEGRATION_KEY` — but they receive no new features.
If your account has any, the **Heartbeat monitors** page shows a banner linking to them. Migrating means creating a monitor that points at the same alert source and moving your pings to the new URL — the alerting settings you already have on the source carry over untouched.
## Examples
{% content-ref url="/pages/-MJ3xwrMP9m9qyteB53i" %}
[Prometheus heartbeat example](/alerting/heartbeat-monitoring/prometheus-heartbeat-example.md)
{% endcontent-ref %}
{% content-ref url="/pages/-MJ3wu5-5cROcxAzcSAH" %}
[CLI heartbeat examples](/alerting/heartbeat-monitoring/cli-heartbeat-examples.md)
{% endcontent-ref %}
{% content-ref url="/pages/6JUKJruULo8rQ3EnRKgk" %}
[Email heartbeat example](/alerting/heartbeat-monitoring/email-heartbeat-example.md)
{% endcontent-ref %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.ilert.com/alerting/heartbeat-monitoring.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.