---
title: "List monitors"
method: GET
path: "/monitors"
tags: ["Monitors"]
---

# List monitors

`GET /monitors`

Lists monitors for the authenticated organization. Supports free-text search (`q` over `search_by` fields, `prefix` or `exact` via `search_type`) plus status/type/tag filters. Results are paginated via the opaque `cursor`.

## Query parameters

- `q` string — Free-text search term, matched against the fields named in `search_by`.
- `search_by` string[], nullable — Comma-separated fields to search with `q`. Defaults to all of them. Note `instructions` only exists on extract monitors.
- `search_type` 'exact' | 'prefix' — `prefix` for as-you-type prefix matching (default), `exact` for full-token matching.
- `status` 'active' | 'paused' | 'failed' — Filter monitors by lifecycle status.
- `target_type` 'page' | 'sitemap' | 'extract' — Filter by target type.
- `change_detection_type` 'exact' | 'semantic' — Filter by change detection type.
- `tags` string[], nullable — Comma-separated list of tags to filter by (matches monitors having any of them).
- `tag` string — Filter to items that have this tag.
- `limit` integer — Maximum number of items to return per page (1-100). Defaults to 25.
- `cursor` string — Opaque pagination cursor from a previous response.

## Response `200`

A paginated list of monitors

- MonitorsListMonitorsResponse
  - `data` MonitorsMonitor[], required
    - `mode` 'web', required — Top-level monitor category. Always `web` today; the concrete behavior is described by `target` and `change_detection`.
    - `id` string, required
    - `name` string, required
    - `target` union, required — Discriminated union describing what the monitor watches.
      - MonitorsPageTarget — Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`.
        - `type` 'page', required
        - `url` string, uri, required
        - `instructions` string — Plain-language goal describing which page changes matter. When provided without change_detection, semantic detection is inferred.
        - `normalize_whitespace` boolean — Normalize whitespace before comparing or analyzing text.
      - MonitorsSitemapTarget — Watch a sitemap for URL additions and removals. Crawled URLs are normalized (lowercased host, no trailing slash/fragment) and scoped to the monitored site and its subdomains before comparison. On a detected difference the sitemap is re-fetched within the same run and only URLs both observations agree on are reported, suppressing transient crawl flaps.
        - `type` 'sitemap', required
        - `url` string, uri, required — Sitemap URL to monitor.
        - `include` string[] — URL path patterns to include (max 50).
        - `exclude` string[] — URL path patterns to exclude (max 50).
        - `max_urls` integer — Maximum number of sitemap URLs to track (capped at 10,000).
      - object — Watch the monitor-relevant pages of a site for meaningful changes. A crawl guided by `schema`/`instructions` selects up to `max_pages` relevant pages to track; each run re-checks exactly those pages, and confirmed content changes are judged for relevance against the monitor's `instructions` (and `schema`, when provided). The tracked page set is refreshed by a periodic re-discovery crawl.
        - `type` 'extract', required
        - `url` string, uri, required — Root URL to extract structured data from.
        - `schema` object — JSON Schema describing the data you care about. It is used three ways: it guides which pages are selected for tracking, it gives the change judge extra context on which changes matter (alongside `instructions`), and it defines the shape of the baseline `data` snapshot on GET /monitors/{monitor_id} (refreshed at most about once a day). It is not a response format for changes: change events and webhook payloads always contain diffs, summaries, and evidence excerpts — never data in this schema's shape. If omitted, a default summary + key-points schema is used.
        - `instructions` string, required — Natural-language instructions guiding which pages and facts to track and which changes to report.
        - `max_pages` integer — Maximum number of pages to track.
        - `max_depth` integer — Optional maximum link depth from the starting URL (0 = only the starting page).
        - `follow_subdomains` boolean
    - `change_detection` union, required — Discriminated union describing how changes are detected.
      - MonitorsExactChangeDetection — Detect exact changes. For page targets, this means visible text diffs. For sitemap targets, this means URL additions and removals.
        - `type` 'exact', required
      - MonitorsSemanticChangeDetection — Detect meaning-level changes to page content, ignoring cosmetic or instruction-irrelevant differences. Which changes are meaningful is judged against the page or extract target's `instructions` (and an extract target's `schema`, when provided).
        - `type` 'semantic', required
        - `confidence_threshold` number
    - `schedule` MonitorsSchedule, required — Run the monitor on a fixed interval defined by a frequency and a unit, e.g. every 6 hours or every 2 days. The total interval (frequency × unit) must be between 10 minutes and 1 year.
      - `type` 'interval', required
      - `frequency` integer, required — Number of units between runs. The resulting interval (frequency × unit) must be at least 10 minutes and at most 1 year (e.g. minimum 10 when unit is minutes; maximum 365 when unit is days).
      - `unit` 'minutes' | 'hours' | 'days', required
    - `webhook` MonitorsNullableWebhookConfig
      - `url` string, uri, required — Webhook URL events are delivered to.
      - `events` string[] — Events delivered to this endpoint. `change.detected` fires only when a run detects a change; `run.completed` fires on every completed run — including runs that detected no change — and embeds the change when one was detected. Defaults to `["change.detected"]` when omitted.
      - `secret` string — Signing secret used to verify webhook authenticity. Each delivery includes an `X-Context-Signature: t=<unix>,v1=<hmac>` header, where the HMAC is SHA-256 over `"{t}.{rawRequestBody}"` keyed by this secret. Recompute it with a constant-time compare and reject stale timestamps to prevent replay. Generated by the API; cannot be set by clients.
    - `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_at` string, date-time, nullable
    - `last_change_at` string, date-time, nullable
    - `next_run_at` string, date-time, nullable — When the next scheduled run is due.
    - `last_error` MonitorsRunError
      - `code` string, required
      - `message` string, required
    - `webhook_failure` MonitorsWebhookFailure
      - `consecutive_failures` integer, required — Number of consecutive delivery attempts that did not succeed.
      - `last_status` 'rejected' | 'failed' | 'skipped_unsafe_url', required — Outcome of the most recent failed delivery. rejected means a non-2xx response; failed means no HTTP response was received; skipped_unsafe_url means the URL failed the public-endpoint safety check.
      - `last_message` string, required — Human-readable description of the most recent failure.
      - `last_failed_at` string, date-time, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `tags` string[] — User-defined tags for grouping and filtering monitors and their changes. Duplicates are removed.
    - `baseline` union — Current baseline: the last observed value the monitor compares new snapshots against. Its shape follows `target.type` (page/sitemap/extract). Only populated on GET /monitors/{monitor_id}; null until the first baseline run completes (and after a target or change_detection update, which resets the baseline).
      - MonitorsPageBaseline — Current baseline of a `page` monitor: the visible page text as last observed.
        - `text` string, required — The page's visible text as last observed.
        - `captured_at` string, date-time, required — When this baseline was last captured or replaced.
      - MonitorsSitemapBaseline — Current baseline of a `sitemap` monitor: the normalized URL set as last observed.
        - `urls` string[], required — The sitemap URLs as last observed (sorted, normalized).
        - `url_count` integer, required — Number of URLs in the baseline.
        - `captured_at` string, date-time, required — When this baseline was last captured or replaced.
      - MonitorsExtractBaseline — Current baseline of an `extract` monitor: the pages it tracks and the structured data as last extracted.
        - `data` unknown, required
        - `urls_analyzed` string[], required — The page URLs the monitor tracks and analyzes for changes.
        - `captured_at` string, date-time, required — When this baseline was last captured or replaced.
  - `has_more` boolean, required
  - `next_cursor` string, nullable, required

## Other responses

- `401` — Unauthorized

---

[API](https://skmtc.net/context/apis/context-dev.md) · [All operations](https://skmtc.net/context/apis/context-dev/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/context/context-dev/revisions/182f532c2552/schema)