Create check
create_checkCreate a new uptime monitoring check for HTTP, TCP, DNS, SSL, databases, or other services and return its UID, slug, placement, and resolved periods.
Instructions
Create a new monitoring check and return it (uid, slug, placement, resolved periods). If you don't know what config shape a given type expects, call list_check_types with type first to fetch a working starting config, then use validate_check to dry-run before creating. An enabled check starts running on its next tick and opens an incident after its confirmation period; pass enabled:false to create it paused. A duplicate slug is rejected with a conflict, never merged — use update_check to change an existing check. Counts against the organization's MaxChecks quota (an over-quota create is refused); reversible with delete_check. Requires the mcp scope (mcp:read tokens are refused) and at least the user role in the organization.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Human-readable name, e.g. "API production". Auto-generated from URL if omitted. | |
| slug | No | URL-friendly slug (3-20 lowercase letters/digits/hyphens), e.g. "api-prod". Auto-generated if omitted. | |
| type | No | Check type. Allowed: http, tcp, icmp, dns, heartbeat, email, domain, ssl, smtp, udp, ssh, pop3, imap, websocket, postgresql, ftp, sftp, js, mysql, redis, mongodb, mssql, oracle, clickhouse, grpc, kafka, mqtt, a2s, minecraft, rabbitmq, snmp, docker, browser, freebox_line, dnsbl, sip, kubernetes, ntp, rdp, vnc, prometheus, private-location, crawl, health, vendor-status. Inferred from config if omitted. | |
| config | Yes | Check-specific config. Shape depends on type. Example for http: {"url": "https://example.com", "method": "GET"}. Use list_check_types with type to discover the shape for other types. | |
| labels | No | Key-value labels for organization and filtering, e.g. {"env":"production","team":"api"}. | |
| period | No | Check interval as HH:MM:SS, e.g. "00:00:30" for 30 seconds, "00:01:00" for 1 minute (default). | |
| enabled | No | Whether the check should run. Default true. | |
| regions | No | Region slugs to pin the check to, e.g. ["eu-west-1","us-east-1"]. An explicit list means placement "pinned": the check runs from exactly these regions and is never moved. When omitted, the check is placed automatically (placement "auto"): the scheduler picks regionCount healthy regions from the org's default_regions, then the system default, then every other declared region, and moves the check off a region that goes dark. (An org whose own default_regions names a private location keeps pinned checks on those defaults.) | |
| placement | No | "pinned" or "auto". Omit to infer it: regions given means pinned, otherwise auto. "auto" cannot be combined with regions. Private (@) regions are pinned-only. | |
| failQuorum | No | Multi-region quorum: how many of the check's regions must be failing, for the confirmation period, before it is down and an incident opens. "all", "majority" or a whole number such as "2" (clamped to the region count). The default is all regions for 1-2 regions and a majority for 3+. Fewer failing regions than the quorum is a "regional issue": the check shows warning and no incident opens. "all" keeps the per-result rule: any passing region resets the confirmation. Omit for the default. | |
| regionPool | No | Automatic placement only: the cloud region slugs the scheduler may choose from, e.g. ["paris","gravelines"]. Omit for any cloud region. Implies placement auto. | |
| description | No | Free-text description shown in the UI. | |
| regionCount | No | Automatic placement only: how many regions run the check (default 2, capped by the eligible regions and the org's checks-per-minute limit; the response carries a PLACEMENT_REGION_COUNT_REDUCED warning when reduced). Implies placement auto. | |
| checkGroupUid | No | Assign the check to a check group (UID or slug), e.g. "core-services". | |
| recoveryPeriodSeconds | No | Wall-clock seconds the check must stay UP before auto-resolving an incident. Any failure inside the window resets the recovery clock. 0 = resolve immediately. Range 0–86400. Default 120. | |
| confirmationPeriodSeconds | No | Wall-clock seconds to wait after the first failure before opening an incident. 0 = open immediately on the first failure. Range 0–86400 (one day). Default 120. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uid | Yes | Check UID. | |
| name | No | Human-readable name. | |
| slug | No | URL-friendly slug. | |
| type | No | Check type, e.g. "http". | |
| config | No | Check-specific configuration for the type. | |
| labels | No | Key-value labels. | |
| period | No | Check interval as HH:MM:SS. | |
| status | No | Synthesized status: up, down, validating, created or degraded. | |
| enabled | No | Whether the check runs. | |
| regions | No | Regions the check runs from. | |
| createdAt | No | RFC3339 creation timestamp. | |
| placement | No | "pinned" or "auto". | |
| description | No | Free-text description. | |
| lastResultAt | No | RFC3339 timestamp of the newest real result. | |
| checkGroupUid | No | Check group UID, when the check belongs to a group. | |
| statusChangedAt | No | RFC3339 timestamp of the last status change. |