Fettle

Mark an open incident as being handled so its repeat alerts stop; the recovery alert still goes out when it resolves. Use it when someone is working on the outage. It does not close the incident (that happens when the monitor recovers) and it is not for status page incidents (post_status_page_update). Requires a key with the write scope. Acknowledging twice keeps the first acknowledgement; on a resolved incident it succeeds without effect on alerts. Returns the incident in the get_incident shape.

Create 1 to 100 monitors in one call, all or nothing; for a single monitor use create_monitor. Requires a key with the write scope. An invalid item, or a batch that would exceed the plan, rejects the whole call and creates nothing: call get_plan_usage first to check the batch fits. Errors name the failing item. A field that fails validation is named by its path, such as monitors.3.target (index 3 is the fourth item; all such errors are reported at once). Any other item error keeps the status create_monitor would give (403 when its interval or regions break the plan or name an unknown region, 404 for an unknown channel id, 422 for its config or its type's region rules) and its reason starts with monitors[3] ("<item name>"): — only the first such item is reported. Read the index only from that leading monitors[N] (the pattern ^monitors\[(\d+)\] after any lead-in such as "Forbidden: " or "Invalid request: "), never from the name, which may itself contain quotes or brackets. A plan-limit 403 without that prefix is about the batch as a whole: together the items would exceed the plan's monitor count or its quota of monitors below 60 seconds. Fix the item or shrink the batch and send the whole call again. Returns monitors: one list_monitors row per created monitor, in request order. The example is a port-list TCP monitor, which takes exactly one region and an interval of at least 300 seconds. Example: {"monitors": [{"name": "db.example.com exposed ports", "type": "TCP", "target": "db.example.com", "interval_seconds": 3600, "timeout_seconds": 10, "regions": ["eu-central"], "config": {"ports": [5432, 6379, 27017], "expected_state": "closed"}}]}

Pause up to 100 monitors in one call, all or nothing: no checks run and each open incident closes without an alert. Use it to stop monitoring a whole project or group found with list_monitors; for one monitor use pause_monitor, and to silence alerts around a deploy while checks keep running use create_maintenance_window instead. Requires a key with the write scope. Pausing a paused monitor is not an error. Returns monitors: the list_monitors rows after the change, in request order. Example: {"monitor_ids": ["<id from list_monitors>", "<id from list_monitors>"]}

Resume up to 100 paused monitors in one call, all or nothing; each goes back to PENDING and is checked on the next tick. For one monitor use resume_monitor; to run a check right away on a monitor that is already running, use check_now. Requires a key with the write scope. Resuming more monitors than the plan's active limit allows is a 403 and nothing changes (see get_plan_usage). A monitor already running is left as it is. Returns monitors: the list_monitors rows after the change, in request order. Example: {"monitor_ids": ["<id from list_monitors>", "<id from list_monitors>"]}

Add and/or remove tags across up to 300 monitors in one call, all or nothing: each monitor ends with (its tags | add) - remove. Use it to retag a fleet; to replace one monitor's whole tag list use update_monitor, to rename or drop a tag everywhere (heartbeats too) use rename_tag or delete_tag. Requires a key with the write scope. At least one of add or remove is required, and they must not share a tag (422). A monitor that would end with more than 10 tags rejects the whole call (422). 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. Returns monitors_updated. Example: {"monitor_ids": ["<id from list_monitors>", "<id from list_monitors>"], "add": ["env:prod"], "remove": ["env:staging"]}

Set the same interval, timeout, regions, channels, threshold or cooldown on up to 100 monitors in one call, all or nothing. For example, move twenty PING monitors to other regions. Not for config or name (use update_monitor, one monitor at a time) or tags (use bulk_update_monitor_tags). Requires a key with the write scope. The plan's rules apply to the result: an interval below the plan minimum, too many fast monitors, too many regions or an unknown region is a 403. A value one monitor cannot take (several regions on an SSL, DNS or port-list TCP monitor, or an interval under 300 on a port-list one) is a 422 that starts with monitors[<i>] ("<name>"). Returns monitors: list_monitors rows, which show the interval but not the other settings; read those with get_monitor. Example: {"monitor_ids": ["<id from list_monitors>", "<id from list_monitors>"], "changes": {"regions": ["eu-central", "us-east"], "interval_seconds": 300}}

Queue one existing monitor to run on the scheduler's next tick instead of waiting out its interval, for example to confirm a fix. It returns the monitor record, not a check result: call get_monitor or list_check_results a moment later for the outcome. To probe a target that has no monitor yet use check_target; to restart a paused monitor use resume_monitor. Requires a key with the write scope. A repeat call for the same monitor within 30 seconds, or a call on a paused monitor, is a silent no-op that returns it unchanged. Calls are limited to 10 per minute per calling address (not per key or organization); past that it is a 429 with the seconds to wait, so pace a run over many monitors.

Run one real check of a target from one region chosen by Fettle, without creating anything. It reports status (up, down, error or unknown), region, response_time_ms, status_code, error and failure_kind. unknown means no definite answer came back, not a failure. Use it before create_monitor to catch a typo or an unreachable host; a down result does not stop you creating the monitor. For a monitor that already exists use check_now. Requires a key with the write scope. It is rate limited per calling address: a 429 whose retry_after says how many seconds to wait. Example: {"type": "HTTP", "target": "https://api.example.com/health"}

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}

Create a one-time or recurring maintenance window that silences alerts for some or all monitors. While a window is in effect its monitors keep being checked, but no incident opens and no alert goes out. Use it around a deploy or reboot instead of pause_monitor; it does not cover heartbeats (use pause_heartbeat). For a recurring schedule run preview_maintenance_window first. Requires a key with the write scope. The plan caps how many windows exist (403 past it or when the plan has none; see max_maintenance_windows in get_plan_usage). An invalid argument or schedule is a 422 naming it. Returns the window. Example: {"name": "Deploy", "scope": "MONITOR", "monitor_ids": ["<id from list_monitors>"], "dtstart": "2026-10-14T22:00:00", "duration_minutes": 30}

Create one monitor that checks a URL, host or port on a schedule from one or more regions, and return it in the get_monitor shape. Use check_target first to catch a typo or an unreachable host; use bulk_create_monitors for several monitors, and create_heartbeat for a job that should report in rather than be probed. Requires a key with the write scope. Plan limits apply (monitor count, minimum interval, monitors faster than 60 seconds, regions per monitor): breaking one is a 403 naming it, so call get_plan_usage first. A paused monitor still counts toward them. An invalid argument is a 422 naming it. The example shows the shape for a plan with one region per monitor; take interval_seconds and regions from the user and get_plan_usage, not from it. Example: {"name": "API", "type": "HTTP", "target": "https://api.example.com/health", "interval_seconds": 600, "timeout_seconds": 10, "regions": ["us-east"], "config": {"expected_status_codes": [200]}, "tags": ["env:prod"]}

Open a new incident on a status page with its first message, to tell the page's visitors about an outage. It is public and emails the page's confirmed subscribers: confirm the wording with the user before calling. Any status but RESOLVED emails every confirmed subscriber at once; RESOLVED records an already closed incident (a postmortem) and emails nobody. To add to an existing incident use post_status_page_update. Requires a key with the write scope. Returns the incident. Example: {"page_id": "<id from list_status_pages>", "title": "API errors", "body": "We are investigating elevated error rates."}

Delete one heartbeat for good: its ping_url stops working (404) and no tool restores it. Use it only when the user asked for deletion; to stop alerts for a while use pause_heartbeat. Requires a key with the write scope. Returns {"success": true}.

Delete one maintenance window; alerts for its monitors resume at once and no tool restores it. To suspend a window but keep it, use update_maintenance_window with enabled false. Requires a key with the write scope. Returns {"success": true}.

Delete one monitor: it stops being checked and disappears from the organization's monitors, and no tool restores it. Use it only when the user explicitly asked for deletion; otherwise prefer pause_monitor, which keeps the monitor and its history. There is no bulk delete. Requires a key with the write scope. Returns {"success": true}.

Remove an incident and its timeline from a status page; it stops showing at once, nothing is sent to subscribers, and no tool restores it. Use it for an incident posted by mistake; to close a real one use post_status_page_update with RESOLVED. Requires a key with the write scope. Returns {"success": true}.

Remove a tag from every monitor and heartbeat that carries it; the items themselves stay, and no tool restores the tag. Use it to retire a tag across the organization; to take it off chosen monitors only use bulk_update_monitor_tags with remove, and to rename it use rename_tag. Requires a key with the write scope. A tag nothing carries is not an error (both counts are 0). Returns from (the tag), monitors_updated and heartbeats_updated.

List the ports that should never be reachable from the internet (databases, queues, admin panels). Returns ports, each a port number and the service that usually listens on it. Use it to pick ports when asked to watch a server for exposed services; it creates nothing. Then create one TCP monitor on the server's public hostname or IP with config {"ports": [...], "expected_state": "closed"} (1 to 20 distinct ports, one region, interval_seconds 300 or more; 3600 is plenty) through create_monitor: it counts as one monitor and fails naming every port that answers.

Read one heartbeat in full, including how long its last run took. It has name, state, period_seconds, grace_seconds, ping_url, last_ping_at, last_success_at, last_start_at, last_duration_ms (how long the last run took, from its /start to its success ping), overdue_at (when it will be reported late), notification_cooldown_seconds, is_active, channel_ids and tags. Use it to answer whether a job ran, how long it took and when it is next due. To find a heartbeat use list_heartbeats; to change it use update_heartbeat; probed monitors are get_monitor.

Read one incident in full, with every alert sent for it. It has id, monitor_id or heartbeat_id (exactly one is set), started_at, resolved_at, cause, cause_detail, last_notified_at, acknowledged_at, acknowledged_by, renotify_count and notification_logs (each alert attempt: id, channel_type, destination, event TRIGGERED, RESOLVED or SSL_EXPIRY, sent_at, status PENDING, SENT or FAILED, and error). Use it to tell who acknowledged an incident and whether its alerts were delivered. destination is an email address, a Telegram chat id, or only scheme://host/… of a webhook. To find incidents use list_incidents; to stop its reminders use acknowledge_incident.

Read one maintenance window with its schedule and its next three occurrences. It has the list_maintenance_windows fields plus next_occurrences, each with start and end. Use it to confirm when a recurring window fires next. To check a schedule before saving it use preview_maintenance_window; to find a window use list_maintenance_windows.

Read one monitor's full configuration and current state. It has type, target, interval_seconds, timeout_seconds, regions, config, status, is_active, confirmation_threshold, notification_cooldown_seconds, channel_ids (empty means every verified, active channel is alerted), tags, badge_enabled, last_checked_at, next_run_at, and for SSL monitors ssl_expires_at and ssl_cert_info. Use it before update_monitor, since a config you send replaces the stored one whole. Not for finding a monitor (list_monitors), its uptime (get_uptime_summary) or why it fails (list_check_results).

Show the organization's plan, its limits and current usage, to check that new monitors, heartbeats or regions fit before creating them or to explain a 403 naming a limit. Region codes and their cities come from list_regions; billing changes happen only in the dashboard. Values are current as of the call. Returns plan (one of FREE, PLUS, PRO, MAX, ENTERPRISE), limits and usage. limits: max_monitors, min_interval_seconds, max_fast_monitors (monitors below fast_interval_threshold_seconds, 60), max_regions per monitor, allowed_regions, max_heartbeats, max_maintenance_windows, history_retention_days, api_rate_limit_per_minute (shared by the whole organization), renotify_interval_seconds and renotify_max_count (how often and how many times an open, unacknowledged incident is alerted again; 0 means no reminders); null means no limit. usage: monitors (paused included), fast_monitors and heartbeats.

Chart one monitor's average response time over time, one series per region, to see where it is slow and since when. Returns monitor_id, window, bucket_seconds and regions, each with region, display_name and points (oldest first, the same buckets in every series: bucket_start, avg_response_time_ms, null when the bucket had no successful check, and sample_count). Every configured region has a series, even an empty one, followed by removed regions that still had checks; points start at the window's start or at the monitor's creation. For uptime use get_uptime_summary; for single checks use list_check_results.

Read one status page with its components. It has the list_status_pages fields, where each component has id, monitor_id, display_name and position. Use it to get the component ids that create_status_page_incident takes as component_ids. To find a page use list_status_pages; for the incidents posted on it use list_status_page_incidents.

Report one monitor's uptime for each UTC day, oldest first and ending today, to find the day an outage or degradation began. Each day has date, uptime_percentage, downtime_seconds, observed_seconds, degraded_seconds, total_checks, up_checks, down_checks, degraded_checks and maintenance_checks. degraded_seconds is the day's time in confirmed DEGRADED status (an ongoing degradation counts up to now; 0 for days before this monitor's status history began, when the status ledger shipped); it does not lower uptime_percentage. A day with degraded_seconds above 0 and no confirmed outage is a degraded (yellow) day in the dashboard; degraded_checks alone does not make one. uptime_percentage is the share of the day's observed time outside confirmed outages (an outage counts from the first failing probe to the first probe that is not DOWN; a failure only one region saw does not count; maintenance counts as up; hours with no checks are left out); a day with no checks and no outage has a null uptime_percentage, not 100. The check counts are informational: a failed check outside a confirmed outage does not lower uptime_percentage. For 24h, 7d and 30d totals use get_uptime_summary. Returns monitor_id and days.

Report one monitor's uptime percentage, average response time and incident count over the last 24 hours, 7 days and 30 days at once, to answer how reliable it has been. For a day-by-day series use get_uptime_daily; for response time per region use get_response_time_by_region; for the individual failures use list_check_results. Returns monitor_id and windows keyed 24h, 7d and 30d, each with uptime_percentage, downtime_seconds, observed_seconds, window_start (later than the window's start when the monitor is younger), total_checks, up_checks, down_checks, degraded_checks, incident_count and avg_response_time_ms. uptime_percentage is the share of observed time outside confirmed outages (an outage counts from the first failing probe to the first probe that is not DOWN; a failure only one region saw does not count; maintenance counts as up; hours with no checks are left out; null when nothing was observed). The check counts are informational: a failed check outside a confirmed outage does not lower uptime_percentage.

List the enabled maintenance windows in effect at this moment, to tell whether a monitor's alerts are silenced now. An ORG-scope window covers every monitor, a MONITOR-scope one its monitor_ids. For every window, including future and disabled ones, use list_maintenance_windows. Returns a plain array (not a page) of list_maintenance_windows items; empty when nothing is silenced.

List the organization's notification channels (up to 100), to get the ids that channel_ids of monitors and heartbeats take. Each has id, type (TELEGRAM, WEBHOOK, SLACK or DISCORD), label, is_verified, is_active and destination_hint (a chat id, a masked address, or a webhook's scheme and host). Only a verified, active channel is alerted; an unverified one can be bound but receives nothing yet, and an inactive or unknown id cannot be bound (404). Email is not a channel: every alert also goes to the account email of whoever created the monitor or heartbeat. Channels are added only in the dashboard.

List one monitor's individual check results, newest first, to find out why it is DOWN: which regions fail and with what status code or error. Each has id, region, checked_at, status, response_time_ms, status_code, error_message, details and maintenance_window_id (set when the check ran inside a window). For totals use get_uptime_summary or get_uptime_daily; for the incident they opened use list_incidents. Returns a page: items plus total (of matching results), page, size and pages.

Find heartbeat (cron / dead-man's-switch) monitors. Each has id, name, state (PENDING until a success ping makes it UP or a /fail ping makes it DOWN; later UP, DOWN or PAUSED), period_seconds, grace_seconds, ping_url, last_ping_at, last_success_at, overdue_at, tags and channel_ids. Use it to get a heartbeat's id or ping_url, or to see which jobs are late (sort status puts DOWN first). Probed URLs and hosts are monitors: use list_monitors for those. For one heartbeat's full record, with its last run's duration, use get_heartbeat. Returns a page: items plus total, page, size and pages.

List the organization's monitor and heartbeat incidents, newest first, to see what is or was down and which alerts went out. Each item has id, monitor_id or heartbeat_id (exactly one is set), started_at, resolved_at (null while open), cause, cause_detail (the raw check error), acknowledged_at and notification_logs: the alerts sent, oldest first, each with id, channel_type (EMAIL, TELEGRAM, WEBHOOK, SLACK or DISCORD), destination (may be masked), event (TRIGGERED for the first alert and every reminder, RESOLVED for the recovery), sent_at, status (PENDING while a webhook, Slack or Discord delivery is still being tried, then SENT or FAILED) and error (the last delivery error). For one incident's full record use get_incident; for the checks behind it use list_check_results; incidents posted on a status page are list_status_page_incidents. An incident resolves by itself when its monitor or heartbeat recovers. Returns a page: items plus total, page, size and pages. An invalid value is a 422 naming the argument. Example: {"status": "open", "size": 50}

List every maintenance window of the organization, enabled or not, in effect or not. Each has id, name, enabled, scope (ORG or MONITOR), dtstart, duration_minutes, rrule, timezone, monitor_ids and created_at. Use it to find a window's id. To learn whether alerts are silenced right now use list_active_maintenance; for a window's upcoming occurrences use get_maintenance_window. Returns a page: items plus total, page, size and pages.

Find monitors in the organization by name, target, type, status or tag. Each row is short: id, name, type, target, status, is_active, tags, interval_seconds, ssl_expires_at and last_checked_at. Use it first to get a monitor's id, or to answer what is broken now (status ["DOWN", "DEGRADED"]) or which certificates expire first (type ["SSL"], sort ssl_expiry). For one monitor's full settings use get_monitor; for heartbeats use list_heartbeats. Returns a page: items plus total, page, size and pages. An invalid value is a 422 naming the argument. Example: {"status": ["DOWN", "DEGRADED"], "size": 100}

List every check region of the platform, to show the user where checks can run. Returns regions, each with code (what a regions argument takes), display_name, city, country_code, group and group_display_name. The organization may use only some of them: to choose regions for a monitor read limits.allowed_regions and max_regions from get_plan_usage instead. For one monitor's per-region timings use get_response_time_by_region.

List the incidents shown on one status page, newest first, both posted by a person and opened by Fettle. Each has id, title, status, is_auto (opened by Fettle from a monitor), started_at, resolved_at, notified_at (when subscribers were first emailed; null if never), component_ids and updates (the timeline, oldest first, each with id, status, body, created_by and created_at). Use it to find the incident_id for post_status_page_update. Monitor outages behind the scenes are list_incidents. Returns a page: items plus total, page, size and pages.

List the organization's public status pages. Each has id, slug, name, description, is_published (publicly visible now), history_days, created_at, groups (each with name, position and its components) and ungrouped_components. Use it to find a page's id before posting an incident on it. For one page use get_status_page; pages are created and edited only in the dashboard. Returns a page of results: items plus total, page, size and pages.

List the tags used in the organization, most-used first, each with monitor_count and heartbeat_count, as items. Call it before tagging anything so you reuse an existing name instead of inventing a near-duplicate. Not a filter: to find the monitors or heartbeats carrying a tag, pass tag to list_monitors or list_heartbeats. Returns every tag at once, not a page.

Pause one heartbeat: it is no longer reported late, pings to its ping_url are accepted but ignored, and its open incident closes without an alert. Use it when the job is stopped on purpose, such as a runner taken out of service; resume_heartbeat undoes it, while delete_heartbeat removes the heartbeat for good. Maintenance windows do not cover heartbeats. Requires a key with the write scope. Pausing a paused heartbeat changes nothing. Returns the heartbeat.

Stop checking one monitor without deleting it: its status becomes PAUSED and an open incident on it closes without a recovery alert. Use it when the user wants a monitor off for an open-ended time. For a planned deploy or reboot prefer create_maintenance_window, which keeps checking but silences alerts; for many monitors use bulk_pause_monitors; to restart checks use resume_monitor. Requires a key with the write scope. Pausing a paused monitor changes nothing. Returns the monitor in the get_monitor shape.

Add a message to an existing status page incident and set its status; RESOLVED closes it. It is public and emails the page's confirmed subscribers: confirm the wording with the user before calling. Every confirmed subscriber gets the update, except that resolving an incident they were never told about stays silent. To open a new incident use create_status_page_incident; to fix only the title, silently, use update_status_page_incident. Requires a key with the write scope. A resolved incident accepts only further RESOLVED updates; any other status is a 409. Returns the incident. Example: {"page_id": "<id from list_status_pages>", "incident_id": "<id from list_status_page_incidents>", "status": "RESOLVED", "body": "Fixed; error rates are back to normal."}

Compute the next three occurrences, each with start and end, that a schedule would produce, without saving anything. Use it to check a recurring schedule before create_maintenance_window or update_maintenance_window; for a saved window's occurrences use get_maintenance_window. Requires a key with the write scope. An invalid schedule is a 422 with the reason. Returns an array. Example: {"dtstart": "2026-10-18T03:00:00", "duration_minutes": 60, "rrule": "FREQ=WEEKLY;BYDAY=SU", "timezone": "Europe/Berlin"}

Rename a tag on every monitor and heartbeat that carries it; an item that already has the new name keeps one copy. Use it to fix a naming scheme across the organization; to change the tags of chosen monitors only use bulk_update_monitor_tags, and to drop a tag use delete_tag. Requires a key with the write scope. A tag nothing carries is not an error (both counts are 0). Returns from, to, monitors_updated and heartbeats_updated. Example: {"from": "prod", "to": "env:prod"}

Resume one paused heartbeat: it goes back to PENDING with no deadline, so it is not reported late until its next success ping restarts the clock. Use it once the job runs again; to change its timing use update_heartbeat. There is no bulk resume for heartbeats. Requires a key with the write scope. Resuming one that is not paused resets it to PENDING the same way. Returns the heartbeat.

Restart checks on one paused monitor: its status goes back to PENDING and it is checked on the scheduler's next tick. For many monitors use bulk_resume_monitors; to check a running monitor right away use check_now. Requires a key with the write scope. Resuming an active monitor is a no-op success. A 403 means the organization already has as many active monitors as its plan allows: pause or delete another one first. Returns the monitor in the get_monitor shape.

Change one heartbeat's name, timing, channels or tags; only the fields you pass change. A new period or grace applies from the next ping: the current deadline (overdue_at) is not recomputed. To stop or restart late alerts use pause_heartbeat or resume_heartbeat instead; ping_url never changes. Requires a key with the write scope. An invalid argument is a 422 naming it; never send null. Returns the heartbeat. Example: {"heartbeat_id": "<id from list_heartbeats>", "grace_seconds": 7200}

Change one maintenance window's name, schedule, scope or monitors, or switch it off with enabled false; only the fields you pass change. While a window is in effect its monitors keep being checked, but no incident opens and no alert goes out. A recurring window cannot become one-time: delete it with delete_maintenance_window and create a new one. Check a new schedule with preview_maintenance_window first. Requires a key with the write scope. An invalid argument is a 422 and a resulting schedule that is invalid (for example a bad rrule) a 406, each with the reason. Returns the window. Example: {"window_id": "<id from list_maintenance_windows>", "enabled": false}

Change one monitor's settings and return it in the get_monitor shape. Only the fields you pass change, and at least one besides monitor_id is required (422 otherwise); type and target never change (create a new monitor instead). Not for pausing or resuming (pause_monitor, resume_monitor), for many monitors at once (bulk_update_monitors) or for tags alone across monitors (bulk_update_monitor_tags). Requires a key with the write scope. Plan limits are checked against the result, as on create_monitor (only moving a monitor below 60 seconds takes a fast slot): breaking one is a 403 naming it. Port-list rules are checked against the result too, so changing only the interval or regions of a port-list TCP monitor can be a 422. Omit a field to keep it; never send null. Example: {"monitor_id": "<id from list_monitors>", "interval_seconds": 600}

Change a status page incident's title without telling anyone: nothing is sent to subscribers. To change its status or add a message use post_status_page_update. Requires a key with the write scope. Returns the incident. Example: {"page_id": "<id from list_status_pages>", "incident_id": "<id from list_status_page_incidents>", "title": "API errors in eu-central"}