13.8Common tasks

All these calls work with an API key. They assume you set $OBSRVLY_KEY and $API as in 13.3. Replace each <…> with your own value.

List your monitors#

bash

curl -s "$API/monitor/obsrvly.v1.MonitorConfigService/ListMonitors" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 50}'

Create a URL monitor checked every minute#

bash

curl -s "$API/monitor/obsrvly.v1.MonitorConfigService/CreateUrlMonitor" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "checkout",
       "url": "https://example.com/health",
       "method": "GET", "intervalSeconds": 60}'

intervalSeconds is required for URL monitors. Your plan's minimum interval still applies.
Other fields you can send: headers, body (base64), locations, assertions, alertChannelIds and timeoutMs.
Other create calls: CreateApiMonitor, CreateBrowserMonitor, CreateHeartbeatMonitor, CreateTcpMonitor, CreateUdpMonitor, CreatePingMonitor, CreateDnsMonitor, CreateCertMonitor, CreateDomainMonitor and BulkCreateUrlMonitors (13.5). Chapter 2 shows each monitor type.

Pause and resume a monitor#

# Pause
curl -s "$API/monitor/obsrvly.v1.MonitorConfigService/UpdateMonitor" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "<monitor-id>", "activated": false}'

# Resume
curl -s "$API/monitor/obsrvly.v1.MonitorConfigService/UpdateMonitor" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "<monitor-id>", "activated": true}'

Mute a monitor until a set time#

bash

curl -s "$API/monitor/obsrvly.v1.MonitorConfigService/UpdateMonitor" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "<monitor-id>", "muted": true,
       "muteUntil": "2026-10-28T09:00:00Z"}'

Send "muted": false to unmute. Send "clearMuteUntil": true to remove the end time, so the mute stays until you remove it. See 3.4.

Run a check now, for example after a deploy#

bash

curl -s "$API/scheduler/obsrvly.v1.SchedulerService/TriggerNow" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"monitorId": "<monitor-id>"}'

You can add location to run from one of the monitor's regions.
You can do this once per monitor every 30 seconds.
The executionId in the answer is not the ID of the result. Wait a little, then read the result with ListExecutions.
To see when the monitor runs next, call GetSchedule with {"monitorId": "<monitor-id>"}. It returns intervalSeconds, activated, nextRunAt and lastRunAt (empty if it never ran).

Read the latest results#

bash

curl -s "$API/result/obsrvly.v1.ResultService/ListExecutions" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"monitorId": "<monitor-id>", "limit": 20}'

Read uptime and response times#

bash

curl -s "$API/result/obsrvly.v1.ResultService/GetMonitorSummary" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"monitorId": "<monitor-id>",
       "window": "SUMMARY_WINDOW_7D"}'

The answer has uptimePct, p50Ms, p95Ms, p99Ms, lastStatus, lastCheckAt and overdue. See 13.6 for how to read -1 and overdue.

p50Ms, p95Ms and p99Ms are response times in ms (milliseconds). Half, 95% and 99% of checks were faster than these.

Acknowledge an incident#

# Find open incidents
curl -s "$API/alert/obsrvly.v1.AlertService/ListIncidents" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "firing"}'

# Acknowledge one, using its alertId
curl -s "$API/alert/obsrvly.v1.AlertService/AcknowledgeIncident" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"alertId": "<alert-id>"}'

Reminders for the incident stop.
The incident shows it was acknowledged by the key, under the key's name.
A notice is sent to your Slack, Teams, Discord, Telegram and PagerDuty channels only. Email and webhook channels get no notice.
You cannot undo an acknowledgement. See 9.6.

Send reminders while an incident stays open#

bash

curl -s "$API/monitor/obsrvly.v1.MonitorConfigService/UpdateMonitor" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "<monitor-id>",
       "renotifyIntervalSeconds": 1800}'

Use 0 to turn reminders off, or a value from 300 to 86400 seconds. See 9.7.

Find out why nobody was alerted#

bash

curl -s "$API/alert/obsrvly.v1.AlertService/ListEvaluations" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"monitorId": "<monitor-id>"}'

Each record has an outcome. It is one of: below_threshold, already_firing, cooldown, awaiting_regions, fired, fired_muted, fired_maintenance, reminder_sent, reminder_muted, reminder_maintenance or reminder_acknowledged.

To see the alert policy in force, call GetAlertPolicy (add monitorId for one monitor). It returns failureThreshold and cooldownSeconds. To change them for one monitor, send them with UpdateMonitor (0 means use the team default). Your team's defaults can be changed only in the dashboard (9.4).

Plan a maintenance window#

bash

curl -s "$API/monitor/obsrvly.v1.MonitorConfigService/CreateMaintenanceWindow" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "database upgrade",
       "startsAt": "2026-11-02T22:00:00Z",
       "endsAt": "2026-11-02T23:00:00Z",
       "monitorIds": ["<monitor-id>"]}'

Leave monitorIds empty to cover every monitor.
A window can be at most 7 days long and can start at most 90 days ahead.
Your team can have up to 100 windows that have not ended.
Use ListMaintenanceWindows to see them and DeleteMaintenanceWindow with {"id": "<window-id>"} to remove one. See 3.5.

Update your status page#

Call GetStatusPage with {} to read the page. Call SaveStatusPage with {"page": {…}} to save it. Each save replaces the whole page, so start from what GetStatusPage returned. See chapter 12.

Read the notification log and test a channel#

ListNotifications (area notification) lists every notification obsrvly tried to send. Each has an event (fire, resolved, reminder or acknowledged) and a status (sent, failed or skipped).
TestChannel with {"channelId": "<channel-id>"} sends a test alert. The answer has a status and an errorMessage. See 10.9.

bash

curl -s "$API/notification/obsrvly.v1.NotificationService/TestChannel" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channelId": "<channel-id>"}'

Check your plan limits#

bash

curl -s "$API/monitor/obsrvly.v1.MonitorConfigService/GetPlanLimitUsage" \
  -H "Authorization: Bearer $OBSRVLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

The answer lists each limit with kind, used, limit and level. level is PLAN_LIMIT_LEVEL_NEARING from 80% and PLAN_LIMIT_LEVEL_REACHED at 100%. A missing used means 0.

Get the screenshot of a failed browser check#

This call is a plain GET, not a POST. Send only the key.

bash

curl -s -H "Authorization: Bearer $OBSRVLY_KEY" \
  "$API/result/v1/monitors/<monitor-id>/executions/<execution-id>/screenshot"
# {"url": "https://...", "expires_at": "2026-10-12T08:19:10Z"}

curl -s -o failure.jpg "<url>"

The link works for 5 minutes and needs no key. Anyone with the link can open the image until then.
Screenshots are kept for 14 days.
A 404 means there is no screenshot for that check.
Step messages in browser results count steps from 0. Step 0 is your first step. See 7.9.