Heartbeat checks
Choose Ping for jobs and systems that can report their own activity.
A check starts with a default location. Add named locations for independent
senders, such as workers in different regions; each has a different secret URL.
Configuration
Section titled “Configuration”| Option | Meaning and constraints |
|---|---|
| Name | Required recognizable check name |
| Schedule type | Interval (default) or cron |
| Interval | Positive seconds; the new-check form starts at one hour |
| Cron expression | Required for cron; must be a valid expression |
| Timezone | Defaults to UTC; used to interpret cron |
| Grace period | Buffer in seconds; default zero; automation requires a nonnegative integer |
| Locations required for healthy | Positive count or blank to require all locations |
| Locations required to avoid failing | Positive count; default one; cannot exceed the healthy requirement |
| Reported value alerting | Check-ins only, above a threshold, or below a threshold |
| Warning and critical values | Both required together for value monitoring; numeric, including fractional values |
| Notification groups | Existing groups in this account; assignment requires alert-management permission |
For above, critical must be greater than warning. For below, critical must be less than warning. Equality with a threshold counts as a breach. The worst reported value across locations is combined with quorum health: the more severe result wins. Locations that have never reported a value are excluded from numeric evaluation. A heartbeat without a valid value does not erase a location’s previously reported value.
Reporting
Section titled “Reporting”GET and POST are accepted at the location’s /ping/<token> URL.
See the ingestion reference for request details.
curl --fail --silent --show-error \ --get --data-urlencode 'value=42' "$PINGSTACK_PING_URL"A POST body can contain JSON or raw diagnostic text. exit_code is stored
as activity data; it does not make a location fail. Every accepted heartbeat
marks an active location up, so send only after the activity you want to
monitor. There are no separate start/fail ingestion endpoints in this API.
If a check is paused, ingestion returns success without recording activity. Pause/resume is not a supported public automation write field.
Evaluate health
Section titled “Evaluate health”After a heartbeat, an interval deadline is calculated from its receipt time. For cron, the next occurrence in the configured timezone is used. An overdue location becomes late after its grace period, but the check’s overall health depends on quorum and numeric thresholds.
Use recipes to report from jobs and scripts. Keep location URLs private; disclosure lets someone falsely report health.