Create a heartbeat monitor
create_heartbeatCreate a heartbeat that alerts when a scheduled job stops reporting. Jobs call the returned ping_url on success, /start when starting, or /fail to mark down.
Instructions
Create a heartbeat: Fettle alerts when a scheduled job stops calling its ping_url. Use it for cron jobs, backups and workers that should report in; to probe a URL, host or port from outside use create_monitor. The job calls ping_url (GET or POST) on success, ping_url + "/start" when it begins (restarts the clock) and ping_url + "/fail" to go DOWN at once. It is never late before its first success ping (a /fail call still marks it DOWN); after that an alert fires period_seconds + grace_seconds after the last ping. Requires a key with the write scope. The plan caps how many heartbeats exist (403 past it; see get_plan_usage). An invalid argument is a 422 naming it. Returns the heartbeat, with ping_url. Example: {"name": "nightly backup", "period_seconds": 86400, "grace_seconds": 3600}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Display name, 1 to 255 characters. | |
| tags | No | Flat labels for grouping and filtering, for example env:prod or service:api, at most 10. Each tag is trimmed, lowercased and deduplicated on write, at most 50 characters of a-z, 0-9 and : _ . / -, starting with a letter or digit. Reuse names from list_tags rather than inventing near-duplicates. | |
| channel_ids | No | Notification channel uuids from list_channels. Omit it or pass [] to alert every verified, active channel of the organization. An id that is not an active channel of this organization is a 404. | |
| grace_seconds | Yes | Extra seconds of silence tolerated after the period before the heartbeat is reported late, 0 to 2592000; it may exceed the period. | |
| period_seconds | Yes | How often the job runs, 60 to 2592000 seconds. To ping every N seconds and be alerted after T seconds of silence, set period_seconds = N and grace_seconds = T - N (T at least N). | |
| notification_cooldown_seconds | No | 60 to 86400 seconds; 1800 when not set on create. Only holds back a duplicate first alert for the same incident within that window. Repeat reminders while an incident stays open and unacknowledged follow the plan's renotify_interval_seconds and renotify_max_count (get_plan_usage; 0 means no reminders) instead, and the recovery alert is never held back. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| name | Yes | ||
| tags | No | ||
| state | Yes | Known values: PENDING, UP, DOWN, PAUSED. | |
| ping_url | Yes | ||
| is_active | Yes | ||
| created_at | Yes | ||
| overdue_at | Yes | ||
| updated_at | Yes | ||
| channel_ids | No | ||
| last_ping_at | Yes | ||
| grace_seconds | Yes | ||
| last_start_at | Yes | ||
| period_seconds | Yes | ||
| last_success_at | Yes | ||
| last_duration_ms | Yes | ||
| notification_cooldown_seconds | Yes |