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

# List monitors

`GET /monitors`

## Request

- Base URL: `https://api.context.dev/v1`
- URL: `https://api.context.dev/v1/monitors`
- Auth: HTTP bearer

List your monitors with optional search and filters.

## Query parameters

- `q` string: Free-text search term, matched against the fields named in `search_by`.
- `search_by` string[], nullable: Fields to search with `q`. Defaults to all fields; page and extract targets can have instructions.
- `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: Always `web`. Optional.
    - `id` string, required
    - `name` string, required
    - `target` union, required: What to watch: a page, a sitemap, or data extracted from a site.
      - MonitorsPageTarget: Watch a single web page. Exact detection reports visible-text diffs; semantic detection judges confirmed stable diffs against `instructions`.
        - `type` 'page', required: Use `page` to watch one web page.
        - `url` string, uri, required: Public HTTP(S) page URL to monitor.
        - `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.
        - `include_selectors` string[]: Monitor these CSS-selected regions. Empty or omitted uses main content. Changes create a new baseline.
        - `exclude_selectors` string[]: Remove matching regions after inclusions. Changes create a new baseline.
        - `actions` WebScrapeAction[], nullable: Optional browser actions executed in array order after the page loads, before content is captured, on every run. Requires a paid plan. Maximum: 5 actions. Changes create a new baseline.
          - union: Browser action discriminated by `do`. Each variant exposes only its applicable fields.
            - WebScrapeWaitAction: Pause for a fixed number of milliseconds before continuing to the next action.
              - …
            - WebScrapePerformAction: Resolve and perform one natural-language browser action.
              - …
            - WebScrapeScrollAction: Scroll the page or a selected scrollable container, waiting adaptively for content and dimensions to settle after each iteration.
              - …
      - MonitorsSitemapTarget: Watch a site’s URL inventory for confirmed additions and removals.
        - `type` 'sitemap', required: Use `sitemap` to watch a site for added or removed URLs.
        - `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: Track relevant pages selected by `schema` and `instructions`; refresh the page set periodically.
        - `type` 'extract', required: Use `extract` to watch structured data across selected pages.
        - `url` string, uri, required: Root URL to extract structured data from.
        - `schema` object: JSON Schema for page selection and the baseline snapshot. Changes return diffs and evidence.
        - `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: Allow page discovery on subdomains of the target site.
    - `change_detection` union, required: How changes are judged. Defaults to `semantic` for extract targets and page targets with `instructions`, otherwise `exact`.
      - MonitorsExactChangeDetection: Detect exact changes. For page targets, this means visible text diffs. For sitemap targets, this means URL additions and removals.
        - `type` 'exact', required: Use `exact` to compare visible text or sitemap URLs.
      - MonitorsSemanticChangeDetection: Detect meaningful content changes using the target’s instructions and optional schema.
        - `type` 'semantic', required: Use `semantic` to judge changes against the target instructions.
        - `confidence_threshold` number: Minimum confidence required to report a meaningful change, from 0 to 1.
    - `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: Use `interval` to run on a repeating schedule.
      - `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: Time unit used with `frequency` to set the run interval.
    - `webhook` MonitorsNullableWebhookConfig
      - `url` string, uri, required: Public HTTP(S) URL that receives events. Slack and GovSlack URLs get formatted messages.
      - `events` string[]: Events to deliver. Defaults to `change.detected`; `run.completed` also includes unchanged runs.
      - `retry` WebhookRetry: Webhook retry settings. Use {} for the default schedule.
        - `delays_seconds` integer[]: Retry delays in seconds, totaling at most 72 hours. Use [] to disable automatic retries.
      - `secret` string: API-generated signing secret. Visible only with full access or `monitors:write` permission.
    - `status` 'active' | 'paused' | 'failed', required: Current state. Failed monitors keep running; paused monitors must be resumed with `status: "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; null while paused.
    - `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[]: Labels for filtering monitors, their changes, and their usage.
    - `baseline` union: Comparison baseline, included on Retrieve. Null until capture completes or after target changes.
      - 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
  - `key_metadata` KeyMetadata: Credits this request used and your remaining balance.
    - `credits_consumed` integer, required: Credits charged for this request.
    - `credits_remaining` integer, required: Credits remaining for your organization.
  - `request_id` string, uuid, required: Unique ID of this request, also in `X-Request-Id`. Include it when contacting support.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: API key permissions or organization settings do not allow this request.
- `429`: Rate limit exceeded. Organization concurrency rejections include structured error_data and subscription settings; follow Retry-After before retrying.
- `503`: Search is temporarily unavailable (`SEARCH_UNAVAILABLE`). Retry or list without search filters.

## Changes

- **2026-10-21** `61627728926b`: 4 warning
  - added the new `NO_PUBLISHED_MARKDOWN` enum value to the `error_code` response property for the response status `400`
  - added the new `NO_PUBLISHED_MARKDOWN` enum value to the `error_code` response property for the response status `401`
  - added the new `NO_PUBLISHED_MARKDOWN` enum value to the `error_code` response property for the response status `403`
  - added the new `NO_PUBLISHED_MARKDOWN` enum value to the `error_code` response property for the response status `503`
- **2026-10-19** `4ddcf49b9fe5`: 5 info
  - added the optional property `error_data` to the response with the `400` status
  - added the optional property `error_data` to the response with the `401` status
  - added the optional property `error_data` to the response with the `403` status
  - added the optional property `error_data` to the response with the `429` status
  - …1 more
- **2026-10-16** `2125f3e94e52`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/context/apis/brand-api/changes/monitors/get.md)

---

[API](https://skmtc.dev/context/apis/brand-api.md) · [All operations](https://skmtc.dev/context/apis/brand-api/llms.txt) · [OpenAPI document](https://skmtc.dev/context/apis/brand-api/revisions/9e2ab7841fb1?raw)