v10

latestOpenAPI 3.1.02026-08-0375143791.1 KB

Monitors

Create a monitor

Creates a monitor. The request body is a union of the supported target/change detection combinations. The monitor runs immediately after creation to create its initial baseline.

post/monitors

Request body

mode'web'

Top-level monitor category. Always web today; the concrete behavior is described by target and change_detection.

namestring required

tagsstring[]

User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed.

Example request

{
  "name": "Acme pricing monitor",
  "tags": [
    "pricing",
    "competitor"
  ],
  "target": {
    "url": "https://acme.com/pricing",
    "instructions": "Report pricing or plan availability changes. Ignore counters, timestamps, testimonials, and navigation."
  },
  "schedule": {
    "frequency": 6,
    "unit": "hours"
  },
  "webhook": {
    "url": "https://example.com/webhook",
    "events": [
      "change.detected",
      "run.completed"
    ],
    "secret": "whsec_8f3a…"
  }
}

Response

Monitor created

mode'web' required

Top-level monitor category. Always web today; the concrete behavior is described by target and change_detection.

idstring required

namestring required

status'active' | 'paused' | 'failed' required

Monitor lifecycle status. failed means the most recent run failed (see the monitor's last_error); failed monitors keep running on schedule and flip back to active on the next successful run. Monitors are auto-paused after repeated consecutive failures or insufficient-credit skips; resume by PATCHing status to active.

last_run_atstring date-time nullable

last_change_atstring date-time nullable

next_run_atstring date-time nullable

When the next scheduled run is due.

created_atstring date-time required

updated_atstring date-time required

tagsstring[]

User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed.

initial_run_idstring nullable required

The baseline run queued by this create call, or null if it could not be queued immediately (in which case the baseline runs on the next scheduled tick). Poll GET /monitors/{monitor_id}/runs/{run_id}.

Example response

{
  "id": "mon_123",
  "name": "Acme pricing monitor",
  "target": {
    "url": "https://acme.com/pricing",
    "instructions": "Report pricing or plan availability changes. Ignore counters, timestamps, testimonials, and navigation."
  },
  "schedule": {
    "frequency": 6,
    "unit": "hours"
  },
  "webhook": {
    "url": "https://example.com/webhook",
    "events": [
      "change.detected",
      "run.completed"
    ],
    "secret": "whsec_8f3a…"
  },
  "last_error": {
    "code": "fetch_failed",
    "message": "The target URL could not be fetched."
  },
  "webhook_failure": {
    "consecutive_failures": 3,
    "last_message": "Webhook endpoint returned HTTP 429."
  },
  "tags": [
    "pricing",
    "competitor"
  ],
  "baseline": {
    "text": "Acme Pricing\nStarter $9/mo…"
  },
  "initial_run_id": "run_123"
}