Create a monitor
create_monitorCreate a scheduled uptime monitor that checks a URL, host, or port from one or more regions and returns the created monitor record.
Instructions
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. Example: {"name": "API", "type": "HTTP", "target": "https://api.example.com/health", "interval_seconds": 300, "timeout_seconds": 10, "regions": ["eu-central"], "config": {"expected_status_codes": [200]}, "tags": ["env:prod"]}
Input Schema
TableJSON 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. | |
| type | Yes | HTTP (a URL answers with an expected status), PING (a host answers ICMP), SSL (a certificate is valid and not about to expire), TCP (a port is open, or a list of ports is closed) or DNS (a record resolves, optionally to an expected value). Cannot be changed after create. | |
| config | No | An object whose fields depend on type, all optional unless stated. HTTP: method (GET, HEAD, POST, PUT, PATCH or DELETE, any case; default GET); expected_status_codes (non-empty list of codes 100 to 599, default [200]); keyword (case-sensitive substring the body must contain, at most 1024 characters, not with HEAD); follow_redirects (default true); verify_ssl (default true; false skips TLS verification, so the monitor can never report TLS_INVALID); request_headers (object of name to value: at most 20, a name at most 128 characters of letters, digits and ! # $ % & ' * + - . ^ _ ` | ~, a value at most 1024 bytes of printable ASCII, space or tab, the whole object at most 8192 bytes as JSON; names differing only in case, and Host, Content-Length, Transfer-Encoding, Connection, Upgrade, TE, Trailer, Keep-Alive, CF-Connecting-IP or any Proxy-* name, are a 422); request_body (string, at most 8192 bytes as UTF-8, needs POST, PUT, PATCH or DELETE). Reads return every request_headers value as the literal __FETTLE_UNCHANGED__; writing that literal back in an update keeps the stored value (on create it is a 422). PING: packet_count (1 to 20, default 4). SSL: warn_before_days (1 to 365, default 14) and port (1 to 65535, default 443). TCP: either port (1 to 65535) with expected_state "open" (default) or "closed", or ports (1 to 20 distinct ports that must all be closed, which needs expected_state "closed", exactly one region and interval_seconds of at least 300; a check fails when any of them accepts a connection, and the monitor goes DOWN once confirmation_threshold failures confirm it). Both port and ports, or neither, is a 422; expected_state values are lowercase. DNS: record_type (A, AAAA, CNAME, MX, TXT or NS; required) and expected_value (at most 2048 characters). With expected_value one answer must equal it (case-insensitive, ignoring surrounding spaces and a trailing dot; exact for TXT); without it any answer passes. MX answers are the mail host names without priority (mail.example.com, not 10 mail.example.com). A and AAAA look up every address of the host, IPv4 and IPv6 alike, and any one may match; write an IPv6 address in its shortest form. Omit it for HTTP, PING or SSL to take the defaults; a TCP or DNS monitor without it is a 422. | |
| target | Yes | What to check, up to 2048 characters. HTTP: an http:// or https:// URL (https:// is added when the scheme is missing; port, path and query are kept). PING, SSL, TCP and DNS: a bare public hostname or IP address with no :port and no path (the port goes in config): host:port is a 422, and a full URL is cut down to its host, losing its port. Hostnames are ASCII (punycode for internationalized domains). localhost, *.localhost and addresses that are not public (private, loopback, link-local, CGNAT 100.64.0.0/10, reserved, unspecified) are a 422. Cannot be changed after create. | |
| regions | Yes | One or more distinct region codes, for example eu-central: the plan's choices are limits.allowed_regions in get_plan_usage. An unknown code, or more regions than the plan's max_regions, is a 403. SSL and DNS monitors take exactly one region (422 otherwise). | |
| is_active | No | Default true. false creates it paused: no check runs until resume_monitor. | |
| 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. | |
| timeout_seconds | Yes | Seconds one check may take before it fails, 1 to 120. | |
| interval_seconds | Yes | Seconds between checks, 30 to 86400. The plan sets a minimum (limits.min_interval_seconds) and caps how many monitors may check more often than every 60 seconds (max_fast_monitors); breaking either is a 403 naming the limit. | |
| confirmation_threshold | No | How many checks in a row must fail in every region before the monitor goes DOWN and an incident opens, 1 to 10; 3 when not set on create. | |
| 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
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| name | Yes | ||
| tags | No | ||
| type | Yes | Known values: HTTP, PING, SSL, TCP, DNS. | |
| config | Yes | ||
| status | Yes | Known values: PENDING, UP, DEGRADED, DOWN, PAUSED. | |
| target | Yes | ||
| regions | Yes | ||
| user_id | Yes | ||
| is_active | Yes | ||
| created_at | Yes | ||
| updated_at | Yes | ||
| channel_ids | No | ||
| next_run_at | Yes | ||
| badge_enabled | No | ||
| ssl_cert_info | No | ||
| ssl_expires_at | Yes | ||
| last_checked_at | Yes | ||
| region_statuses | Yes | Per-region latest status, sorted by region name. Built from ``region_snapshots``; ``job_id`` is dropped (internal dedup key) and malformed/partial snapshot rows are skipped rather than failing the read. | |
| timeout_seconds | Yes | ||
| interval_seconds | Yes | ||
| confirmation_threshold | Yes | ||
| notification_cooldown_seconds | Yes |