Skip to content
StatusOwlDocs

Monitors API

The two endpoints that exist: list monitors and retrieve a monitor. Both read-only.

Last updated

The Monitors API exposes monitor configuration for the calling key's organization. These two endpoints are the entire public API. Both require the monitors:read scope.

EndpointScope
GET /v1/monitorsmonitors:read
GET /v1/monitors/{monitor_uuid}monitors:read

There are no POST, PATCH or DELETE endpoints, no incident endpoints, no status-page endpoints, and no check-result endpoints. Manage everything from the dashboard.

Base URL

text
https://api.statusowl.net/v1

List monitors

http
GET /v1/monitors

Returns monitors in the calling key's organization, newest first.

Query parameters

ParameterTypeDefaultDescription
pageinteger ≥ 11Page number
per_pageinteger 1–10025Results per page
typestring—http, https, tcp or ping
is_activetrue / false—Filter by active state

Example

bash
curl "https://api.statusowl.net/v1/monitors?type=http&per_page=10" \
  -H "Authorization: Bearer sowl_live_xxxxxxxxxxxxxxxxxxxx"

Response

json
{
  "data": [
    {
      "monitor_uuid": "9b6f6c8e-1f70-4b9b-87a0-9f3a8a8a4a01",
      "name": "Marketing site",
      "type": "https",
      "target": "https://statusowl.net",
      "port": null,
      "interval": 60,
      "regions": ["global"],
      "maintenance_mode": false,
      "is_active": true,
      "last_check_at": "2026-08-05T19:14:02.118Z",
      "last_status": "up",
      "last_response_time_ms": 142,
      "created_at": "2026-06-01T15:21:08.422Z",
      "updated_at": "2026-07-12T11:03:55.901Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "total": 1,
    "total_pages": 1
  }
}

Retrieve a monitor

http
GET /v1/monitors/{monitor_uuid}

Returns the full configuration for one monitor, including the HTTP-specific fields the list endpoint omits.

Response

json
{
  "data": {
    "monitor_uuid": "9b6f6c8e-1f70-4b9b-87a0-9f3a8a8a4a01",
    "name": "Marketing site",
    "type": "https",
    "target": "https://statusowl.net",
    "port": null,
    "interval": 60,
    "regions": ["global"],
    "maintenance_mode": false,
    "description": "Public marketing site",
    "is_active": true,
    "last_check_at": "2026-08-05T19:14:02.118Z",
    "last_status": "up",
    "last_response_time_ms": 142,
    "http_method": "GET",
    "expected_status_codes": [200, 301],
    "follow_redirects": true,
    "timeout_ms": 10000,
    "created_at": "2026-06-01T15:21:08.422Z",
    "updated_at": "2026-07-12T11:03:55.901Z"
  }
}

A monitor that does not exist, or belongs to another organization, returns 404. The two cases are not distinguished — that would leak the existence of foreign UUIDs.

Field reference

FieldTypeNotes
monitor_uuidUUIDStable identifier
namestringHuman-readable label; also the label on a status page
typeenumhttp, https, tcp or ping
targetstringURL for HTTP types; hostname or IP for tcp / ping
portinteger / nullTCP port; null otherwise
intervalintegerCheck interval in seconds
regionsstring[]Always exactly one entry — see Monitoring regions
maintenance_modebooleanWhen true, the monitor is not checked
descriptionstring / nullDetail endpoint only
is_activebooleanInactive monitors are not scheduled
last_check_attimestamptz / nullMost recent check
last_statusstring / nullup, down, or null before the first check
last_response_time_msinteger / nullMost recent latency
http_methodenum / nullDetail only
expected_status_codesinteger[] / nullDetail only
follow_redirectsboolean / nullDetail only
timeout_msinteger / nullDetail only
created_attimestamptz
updated_attimestamptz

The list endpoint omits description, http_method, expected_status_codes, follow_redirects and timeout_ms. Fetch a single monitor for those.

Errors

StatusCause
400Invalid query or path parameter (type=foo, per_page=500, a non-UUID id)
401Missing, malformed, revoked or expired key
403Missing monitors:read, or the source IP is not on the key's allowlist
404No such monitor in the calling organization
429Rate limit or quota exceeded

Full reference in Errors.

Not available

  • Write endpoints. The monitors:write scope exists in the catalog and no endpoint consumes it. On the roadmap.
  • Check results and uptime data. No time-series endpoint — no uptime percentages, response-time series or per-day history. The metrics:read scope is reserved for this and grants access to nothing today.
  • Incidents, status pages, maintenance, audit logs. No endpoints.
  • Bulk operations. List with per_page=100 and iterate.

See also