Heartbeats are the inside-out counterpart to URL monitors. Instead of HostAtlas probing your endpoint, your script pings a HostAtlas URL after every successful run. If the ping is late, we alert you.

Typical uses:

• Nightly database backups.
• Weekly log rotation or report generation.
• Any cron job or systemd timer where “it didn’t run” is the failure mode.

Open the page from the sidebar under Monitoring → Monitors → Heartbeats, or directly at /heartbeats.

What you see

The heartbeat list shows every configured heartbeat with:

• Name and search-friendly slug.
• Current status — ok, missed (past due but within grace period), or fail (past grace period).
• Expected interval and grace period.
• Last ping timestamp.
• Ping count and recent event history.

Header KPIs: total, ok, missed, failed.

Click a row to open the heartbeat detail:

• Full ping URL (with copy button).
• Latest 50 heartbeat events with timestamps and status.
• Linked object, if any — for example a discovered cron job on a specific server.

What you can do

From the list:

• New heartbeat — opens the create form.
• Edit — updates the name, expected interval, and grace period. Edit opens as a modal on the list page.
• Delete — removes the heartbeat. Any pings to the old URL after deletion return 404.

Creating a heartbeat

The form asks for three things:

Field	Notes
Name	Free-form label used in alerts.
Expected interval	How often the script should ping, in seconds. Minimum 60.
Grace period	How long we wait past the expected time before flipping to fail, in seconds.

On save, HostAtlas generates a unique slug and gives you a URL of the form:

https://ping.hostatlas.app/{slug}

Wire it into your script:

# End of nightly-backup.sh
rsync … && curl -fsS -m 10 --retry 3 https://ping.hostatlas.app/{slug}

The slug is a UUID, so it is safe to keep in a private repo or a .env file.

Ping semantics

The ping URL accepts optional query parameters so long-running jobs can report richer state:

• No suffix — a plain “ok” ping, resets the miss timer.
• ?start — the job has begun. Useful to measure run duration and to distinguish “never started” from “started but failed”.
• ?ok — the job finished successfully (same as no suffix).
• ?fail — the job started but failed. Flips status to fail immediately regardless of the interval.

How it works

A background job runs on a short cadence and looks at every heartbeat. For each one it compares “now” to the last ping timestamp:

• now – last_ping within the expected interval → ok.
• Past the interval but within the grace period → missed (yellow, no alert yet).
• Past the interval + grace period → fail (red, fires an alert).

Alerts route through the normal Alert Rules engine — target Heartbeat as the source and pick a notification channel. During a Maintenance Window heartbeat alerts are suppressed.

Creating a heartbeat from the CLI

If you use the hostatlas-backup CLI, you can manage heartbeats without opening the web UI:

hostatlas-backup heartbeat list
hostatlas-backup heartbeat new "nightly-postgres"

The new command creates the heartbeat and prints the ping URL, ready to paste into backup.yml. The backup CLI then handles ?start, ?ok, and ?fail for you automatically on every run.

Plan gates

Every plan includes a set number of heartbeats. When you hit the cap the create form redirects to /billing with a toast — upgrade or delete unused heartbeats to make room.

Related

• Monitors — the umbrella that covers URL monitors and heartbeats.
• Cron Jobs — discovered cron entries can be linked to a heartbeat.
• Backup Runs — the dashboard for hostatlas-backup, which uses heartbeats natively.
• Alerts — route heartbeat misses to notification channels.