Heartbeat Monitors Reference

Heartbeat Monitors are used to monitor any system that can make an outbound HTTP request to signal its status.

For practical examples and integration patterns, see our Use Cases guide and Getting Started guide. To set up alerting for your monitors, see Setting Up Alerts.

Configuration Fields

When creating or updating a Heartbeat Monitor, the following fields are available:

Field	Type	Description
name	String	A human-readable name for the monitor.
schedule	String	How often a pulse is expected. Can be a simple interval (every 5 minutes, hourly, daily) or a standard cron expression (*/5 * * * *). Required.
grace	Duration String	The grace period to wait after the expected pulse time before marking the monitor as “Down”. E.g., 10m, 1h. Required.
timezone	String	The IANA time zone identifier for cron schedules (e.g., America/New_York, UTC). Defaults to your organization’s time zone setting.
tags	Array<String>	A list of tags to categorize and filter monitors.
expected_runtime	Object	An object with min and max duration strings (e.g., 30s, 5m). If a job completes outside this range, its status is set to “Degraded”.
payload_scanning	Object	Configure keywords to scan for in the POST body of a pulse. The success_keyword or failure_keyword can determine the monitor’s status.
payload_metrics	Array<Object>	Define rules (e.g., using JSONPath) to extract numerical values from JSON payloads. These are tracked as simple time-series metrics associated with the monitor.

Pulse Endpoints

Each Heartbeat Monitor has a set of unique, secret URLs to signal its status. The base URL is https://pulse.9n9s.com/{uuid}.

Endpoint	Method	Description
/	GET, POST	Signals successful completion. A POST request can include a body for log/output capture.
/start	GET, POST	Signals the beginning of a job run. Resets the timer and sets the status to “Started”. Enables runtime tracking.
/fail	GET, POST	Signals immediate failure. A POST can include an error message or logs.
/{exit_code}	GET, POST	Explicitly signals the outcome with an integer exit code. 0 is success, any non-zero value is a failure.

Statuses

A Heartbeat Monitor can have one of the following statuses:

Status	Description
New	The monitor has been created but has never received a pulse.
Up	The monitor has received a successful pulse within the expected schedule.
Down	The monitor did not receive a successful pulse within the schedule + grace period.
Late	The monitor’s pulse is overdue according to its schedule, but it is still within its grace period.
Started	The monitor has received a /start pulse but has not yet received a completion pulse.
Degraded	The monitor received a successful pulse, but its runtime was outside the configured expected_runtime range.
Paused	The monitor’s alerting has been manually paused by a user. Checks are still recorded.