Monitors

Monitors are the unit of uptime tracking. Each monitor runs a check (HTTP, TCP, DNS, ping, heartbeat, or custom) on a schedule and emits a state series you can alert on.

Endpoints

Method	Path	Description	Scope
GET	/api/v1/monitors	List monitors.	monitors
POST	/api/v1/monitors	Create a monitor.	monitors
GET	/api/v1/monitors/{id}	Read a monitor.	monitors
PATCH	/api/v1/monitors/{id}	Update a monitor.	monitors
DELETE	/api/v1/monitors/{id}	Delete a monitor.	monitors
POST	/api/v1/monitors/{id}/pause	Pause scheduling.	monitors
POST	/api/v1/monitors/{id}/resume	Resume scheduling.	monitors
POST	/api/v1/monitors/{id}/mute	Mute alerts without pausing checks.	monitors
POST	/api/v1/monitors/{id}/unmute	Unmute.	monitors
GET	/api/v1/monitors/{id}/checks	List recent check results.	monitors
GET	/api/v1/monitors/{id}/uptime	Uptime percentage over a window.	monitors
GET	/api/v1/monitors/{id}/latency	Latency histogram over a window.	monitors
PUT	/api/v1/monitors/{id}/labels	Replace label set.	monitors
DELETE	/api/v1/monitors/{id}/labels/{key}	Remove one label.	monitors
GET	/api/v1/monitors/check-stats	Aggregate check counters across the org.	monitors
POST	/api/v1/heartbeat/{monitorID}	Heartbeat ping (no body).	heartbeat

Create a monitor

POST /api/v1/monitors

{
  "name": "Public API",
  "type": "http",
  "target": "https://api.example.com/health",
  "interval_seconds": 30,
  "timeout_seconds": 5,
  "regions": ["us-east-1", "eu-west-1"],
  "http": {
    "method": "GET",
    "expected_status": [200, 204],
    "follow_redirects": true,
    "headers": { "User-Agent": "YipYap" }
  },
  "labels": { "env": "prod", "team": "platform" }
}

Field	Required	Notes
name	yes	1-120 chars.
type	yes	http, tcp, dns, ping, heartbeat.
target	yes	URL, host:port, or hostname depending on type.
interval_seconds	no	Default per-type (HTTP=60, heartbeat=none). Min per plan tier.
timeout_seconds	no	Default 10, max 60.
regions	no	Plan-gated; Free tier runs from a single region.
http.*, tcp.*, dns.*, ping.*	no	Type-specific options. See the per-type monitor docs.
labels	no	Free-form string→string. Used by monitor groups and routing filters.

Response: 201 Created with the full monitor document, including the generated id and (for heartbeat monitors) integration_key.

Read a monitor

GET /api/v1/monitors/{id} returns the same shape as the create response plus:

{
  "current_state": "up",
  "current_state_since": "2026-04-24T10:00:00Z",
  "last_check_at": "2026-04-24T17:40:00Z"
}

Update a monitor

PATCH /api/v1/monitors/{id} with a partial body. Changing type is not supported; delete and recreate.

List monitors

GET /api/v1/monitors

Query parameters:

Parameter	Description
q	Search over name, target, labels.
state	Filter by up, down, degraded, paused, muted.
label.{key}	Filter by exact label match (e.g. label.env=prod).
group_id	Members of a monitor group.
sort	created_at, name, last_state_change. Prefix - for descending.
limit, cursor	See Conventions.

Check history

GET /api/v1/monitors/{id}/checks?from=2026-04-24T00:00:00Z&to=2026-04-24T23:59:59Z&limit=200

Returns chronological check results: timestamp, region, result (up/down/degraded), latency, status code (HTTP), error message if any.

Uptime & latency

GET /api/v1/monitors/{id}/uptime?window=24h returns:

{
  "data": {
    "monitor_id": "01HX...",
    "window": "24h",
    "uptime_percent": 99.87,
    "total_checks": 2880,
    "failed_checks": 4
  }
}

GET /api/v1/monitors/{id}/latency?window=24h returns a percentile histogram (p50/p95/p99).

Related resources

• Monitor Groups: logical grouping + cascade rules.
• Custom States: bring-your-own state semantics.
• Events API: trigger alerts from external systems.
• Heartbeat Checks: dead-man’s-switch monitors.