> ## Documentation Index
> Fetch the complete documentation index at: https://docs.context.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# List Monitors
> List your organization's monitors with free-text search plus status, target type, and tag filters.
0 Credits
## OpenAPI
````yaml GET /monitors
openapi: 3.1.0
info:
title: Context API
description: API for retrieving context data from any website
version: 1.0.0
servers:
- url: https://api.context.dev/v1
security: []
tags:
- name: Batch
description: Scrape many pages or crawl a site asynchronously.
- name: Monitors
description: >-
Monitor pages, sitemaps, and extracted website data for exact or semantic
changes. Webhook payloads are documented by the
MonitorsChangeDetectedWebhookPayload and
MonitorsRunCompletedWebhookPayload schemas.
- name: WebDBs
description: Create structured tables from web pages and keep them up to date.
- name: News
description: >-
Search live first-party RSS and free historical news data by company
identity.
paths:
/monitors:
get:
tags:
- Monitors
summary: List monitors
description: >-
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`.
operationId: listMonitors
parameters:
- schema:
type: string
maxLength: 200
description: >-
Free-text search term, matched against the fields named in
`search_by`.
example: pricing
required: false
description: >-
Free-text search term, matched against the fields named in
`search_by`.
name: q
in: query
- schema:
type:
- array
- 'null'
items:
type: string
enum:
- name
- url
- instructions
- tags
description: >-
Comma-separated fields to search with `q`. Defaults to all of
them. Note `instructions` only exists on extract monitors.
example: name,url
required: false
description: >-
Comma-separated fields to search with `q`. Defaults to all of them.
Note `instructions` only exists on extract monitors.
name: search_by
in: query
- schema:
type: string
enum:
- exact
- prefix
description: >-
`prefix` for as-you-type prefix matching (default), `exact` for
full-token matching.
required: false
description: >-
`prefix` for as-you-type prefix matching (default), `exact` for
full-token matching.
name: search_type
in: query
- schema:
type: string
enum:
- active
- paused
- failed
description: Filter monitors by lifecycle status.
required: false
description: Filter monitors by lifecycle status.
name: status
in: query
- schema:
type: string
enum:
- page
- sitemap
- extract
description: Filter by target type.
required: false
description: Filter by target type.
name: target_type
in: query
- schema:
type: string
enum:
- exact
- semantic
description: Filter by change detection type.
required: false
description: Filter by change detection type.
name: change_detection_type
in: query
- schema:
type:
- array
- 'null'
items:
type: string
minLength: 1
maxLength: 50
maxItems: 20
description: >-
Comma-separated list of tags to filter by (matches monitors having
any of them).
example: pricing,competitor
required: false
description: >-
Comma-separated list of tags to filter by (matches monitors having
any of them).
name: tags
in: query
- schema:
type: string
description: Filter to items that have this tag.
example: pricing
required: false
description: Filter to items that have this tag.
name: tag
in: query
- schema:
type: integer
minimum: 1
maximum: 100
description: >-
Maximum number of items to return per page (1-100). Defaults to
25.
required: false
description: Maximum number of items to return per page (1-100). Defaults to 25.
name: limit
in: query
- schema:
type: string
description: Opaque pagination cursor from a previous response.
required: false
description: Opaque pagination cursor from a previous response.
name: cursor
in: query
responses:
'200':
description: A paginated list of monitors
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
content:
application/json:
schema:
$ref: '#/components/schemas/MonitorsListMonitorsResponse'
'401':
$ref: '#/components/responses/MonitorsUnauthorized'
security:
- bearerAuth: []
x-codeSamples:
- lang: JavaScript
source: |-
import ContextDev from 'context.dev';
const client = new ContextDev({
apiKey: process.env['CONTEXT_DEV_API_KEY'], // This is the default and can be omitted
});
const monitors = await client.monitors.list();
console.log(monitors.data);
- lang: Python
source: |-
import os
from context.dev import ContextDev
client = ContextDev(
api_key=os.environ.get("CONTEXT_DEV_API_KEY"), # This is the default and can be omitted
)
monitors = client.monitors.list()
print(monitors.data)
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/context-dot-dev/context-go-sdk\"\n\t\"github.com/context-dot-dev/context-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := contextdev.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tmonitors, err := client.Monitors.List(context.TODO(), contextdev.MonitorListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", monitors.Data)\n}\n"
- lang: Ruby
source: |-
require "context_dev"
context_dev = ContextDev::Client.new(api_key: "My API Key")
monitors = context_dev.monitors.list
puts(monitors)
- lang: PHP
source: >-
monitors->list(
changeDetectionType: 'exact',
cursor: 'cursor',
limit: 1,
q: 'pricing',
searchBy: ['name'],
searchType: 'exact',
status: 'active',
tag: 'pricing',
tags: ['x'],
targetType: 'page',
);
var_dump($monitors);
} catch (APIException $e) {
echo $e->getMessage();
}
- lang: CLI
source: |-
context-dev monitors list \
--api-key 'My API Key'
components:
headers:
RateLimitLimit:
description: >-
Maximum requests allowed in the current fixed one-minute window.
Returned when the authenticated API key has a per-minute rate limit.
schema:
type: integer
minimum: 1
RateLimitRemaining:
description: >-
Requests remaining in the current fixed one-minute window. Returned when
the authenticated API key has a per-minute rate limit.
schema:
type: integer
minimum: 0
RateLimitReset:
description: >-
Unix timestamp in seconds when the current rate-limit window resets.
Returned when the authenticated API key has a per-minute rate limit.
schema:
type: integer
schemas:
MonitorsListMonitorsResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/MonitorsMonitor'
has_more:
type: boolean
next_cursor:
type:
- string
- 'null'
required:
- data
- has_more
- next_cursor
additionalProperties: false
MonitorsMonitor:
type: object
properties:
mode:
$ref: '#/components/schemas/MonitorsMode'
id:
type: string
example: mon_123
name:
type: string
example: Acme pricing monitor
target:
$ref: '#/components/schemas/MonitorsTarget'
change_detection:
$ref: '#/components/schemas/MonitorsChangeDetection'
schedule:
$ref: '#/components/schemas/MonitorsSchedule'
webhook:
$ref: '#/components/schemas/MonitorsNullableWebhookConfig'
status:
$ref: '#/components/schemas/MonitorsMonitorStatus'
last_run_at:
type:
- string
- 'null'
format: date-time
last_change_at:
type:
- string
- 'null'
format: date-time
next_run_at:
type:
- string
- 'null'
format: date-time
description: When the next scheduled run is due.
last_error:
anyOf:
- allOf:
- $ref: '#/components/schemas/MonitorsRunError'
- type: 'null'
description: >-
Error from the most recent failed run; null when the last run
succeeded.
webhook_failure:
allOf:
- $ref: '#/components/schemas/MonitorsWebhookFailure'
nullable: true
description: >-
Present while webhook deliveries are failing consecutively; null
when deliveries are healthy or no webhook is configured. Cleared on
the next successful delivery and when the webhook URL changes.
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
tags:
type: array
items:
type: string
minLength: 1
maxLength: 50
maxItems: 20
uniqueItems: true
description: >-
User-defined tags for grouping and filtering monitors and their
changes. Duplicates are removed.
example:
- pricing
- competitor
baseline:
oneOf:
- $ref: '#/components/schemas/MonitorsPageBaseline'
- $ref: '#/components/schemas/MonitorsSitemapBaseline'
- $ref: '#/components/schemas/MonitorsExtractBaseline'
- type: 'null'
description: >-
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).
required:
- mode
- id
- name
- target
- change_detection
- schedule
- status
- created_at
- updated_at
additionalProperties: false
title: Monitor
description: >-
A web monitor. `mode` is the constant `web`; behavior is described by
`target` (page/sitemap/extract) and `change_detection` (exact/semantic).
ErrorResponse:
type: object
properties:
message:
type: string
description: Error message
error_code:
type: string
enum:
- INTERNAL_ERROR
- VALID
- NOT_FOUND
- FORBIDDEN
- USAGE_EXCEEDED
- RATE_LIMITED
- UNAUTHORIZED
- DISABLED
- PAID_PLAN_REQUIRED
- INSUFFICIENT_PERMISSIONS
- TIMEOUT_EXCEEDS_MAXIMUM
- WEBSITE_ACCESS_ERROR
- WEBSITE_BLOCKED
- WEBSITE_NOT_FOUND
- PDF_SKIPPED
- PDF_IMAGES_ONLY
- EXTERNAL_PROVIDER_ERROR
- INPUT_VALIDATION_ERROR
- ZDR_NOT_SUPPORTED
- ZDR_NOT_ENABLED
- FREE_EMAIL_DETECTED
- DISPOSABLE_EMAIL_DETECTED
- REQUEST_TIMEOUT
- COLD_DOMAIN_TIMEOUT_TOO_LOW
- UNSUPPORTED_CONTENT
- CONTENT_TOO_LARGE
- MONITOR_PAUSED
- MONITOR_NO_WEBHOOK
- COLLECTION_PAUSED
- MONITOR_LIMIT_EXCEEDED
- SEARCH_UNAVAILABLE
- BATCH_LIMIT_EXCEEDED
- BATCH_NOT_CANCELLABLE
- BATCH_NOT_COMPLETED
- IDEMPOTENCY_KEY_CONFLICT
description: Error code indicating the type of error
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
MonitorsMode:
type: string
enum:
- web
description: >-
Top-level monitor category. Always `web` today; the concrete behavior is
described by `target` and `change_detection`.
title: Monitor mode
MonitorsTarget:
oneOf:
- $ref: '#/components/schemas/MonitorsPageTarget'
- $ref: '#/components/schemas/MonitorsSitemapTarget'
- allOf:
- $ref: '#/components/schemas/MonitorsExtractTarget'
- description: >-
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.
discriminator:
propertyName: type
mapping:
page:
$ref: '#/components/schemas/MonitorsPageTarget'
sitemap:
$ref: '#/components/schemas/MonitorsSitemapTarget'
extract:
$ref: '#/components/schemas/MonitorsExtractTarget'
description: Discriminated union describing what the monitor watches.
MonitorsChangeDetection:
oneOf:
- $ref: '#/components/schemas/MonitorsExactChangeDetection'
- $ref: '#/components/schemas/MonitorsSemanticChangeDetection'
discriminator:
propertyName: type
mapping:
exact:
$ref: '#/components/schemas/MonitorsExactChangeDetection'
semantic:
$ref: '#/components/schemas/MonitorsSemanticChangeDetection'
description: Discriminated union describing how changes are detected.
MonitorsSchedule:
oneOf:
- $ref: '#/components/schemas/MonitorsIntervalSchedule'
discriminator:
propertyName: type
mapping:
interval:
$ref: '#/components/schemas/MonitorsIntervalSchedule'
description: >-
Discriminated union describing how the monitor is scheduled. Only
`interval` is supported today; `cron` and `exact_time` are reserved for
future use.
MonitorsNullableWebhookConfig:
anyOf:
- allOf:
- $ref: '#/components/schemas/MonitorsWebhookConfig'
- type: 'null'
MonitorsMonitorStatus:
type: string
enum:
- active
- paused
- failed
description: >-
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`.
MonitorsRunError:
type: object
properties:
code:
type: string
example: fetch_failed
message:
type: string
example: The target URL could not be fetched.
required:
- code
- message
additionalProperties: false
MonitorsWebhookFailure:
type: object
properties:
consecutive_failures:
type: integer
minimum: 1
description: Number of consecutive delivery attempts that did not succeed.
example: 3
last_status:
type: string
enum:
- rejected
- failed
- skipped_unsafe_url
description: >-
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:
type: string
description: Human-readable description of the most recent failure.
example: Webhook endpoint returned HTTP 429.
last_failed_at:
type: string
format: date-time
required:
- consecutive_failures
- last_status
- last_message
- last_failed_at
additionalProperties: false
MonitorsPageBaseline:
type: object
properties:
text:
type: string
description: The page's visible text as last observed.
example: |-
Acme Pricing
Starter $9/mo…
captured_at:
type: string
format: date-time
description: When this baseline was last captured or replaced.
required:
- text
- captured_at
additionalProperties: false
title: Page baseline
description: >-
Current baseline of a `page` monitor: the visible page text as last
observed.
MonitorsSitemapBaseline:
type: object
properties:
urls:
type: array
items:
type: string
description: The sitemap URLs as last observed (sorted, normalized).
example:
- https://acme.com/blog/launch
- https://acme.com/pricing
url_count:
type: integer
description: Number of URLs in the baseline.
example: 2
captured_at:
type: string
format: date-time
description: When this baseline was last captured or replaced.
required:
- urls
- url_count
- captured_at
additionalProperties: false
title: Sitemap baseline
description: >-
Current baseline of a `sitemap` monitor: the normalized URL set as last
observed.
MonitorsExtractBaseline:
type: object
properties:
data:
description: >-
The extracted structured data, matching the monitor's extraction
schema (same shape as the /web/extract endpoint's `data`). Refreshed
when the monitor re-discovers its page set (at most about once a
day); `null` when no extraction has been captured yet.
example:
plans:
- name: Starter
price: $9/mo
urls_analyzed:
type: array
items:
type: string
description: The page URLs the monitor tracks and analyzes for changes.
example:
- https://acme.com/pricing
captured_at:
type: string
format: date-time
description: When this baseline was last captured or replaced.
required:
- data
- urls_analyzed
- captured_at
additionalProperties: false
title: Extract baseline
description: >-
Current baseline of an `extract` monitor: the pages it tracks and the
structured data as last extracted.
KeyMetadata:
type: object
properties:
credits_consumed:
type: integer
description: The number of credits consumed by this request.
credits_remaining:
type: integer
description: >-
The number of credits remaining for your organization after this
request.
required:
- credits_consumed
- credits_remaining
description: >-
Metadata about the API key used for the request. Included in every
response whenever a valid API key is provided, even when the response
status is not 200.
MonitorsPageTarget:
type: object
properties:
type:
type: string
enum:
- page
url:
type: string
format: uri
example: https://acme.com/pricing
instructions:
type: string
minLength: 1
maxLength: 2000
description: >-
Plain-language goal describing which page changes matter. When
provided without change_detection, semantic detection is inferred.
example: >-
Report pricing or plan availability changes. Ignore counters,
timestamps, testimonials, and navigation.
normalize_whitespace:
type: boolean
default: true
description: Normalize whitespace before comparing or analyzing text.
required:
- type
- url
additionalProperties: false
description: >-
Watch a single web page. Exact detection reports visible-text diffs;
semantic detection judges confirmed stable diffs against `instructions`.
title: Page target
MonitorsSitemapTarget:
type: object
properties:
type:
type: string
enum:
- sitemap
url:
type: string
format: uri
description: Sitemap URL to monitor.
example: https://acme.com/sitemap.xml
include:
type: array
items:
type: string
minLength: 1
maxLength: 200
maxItems: 50
description: URL path patterns to include (max 50).
example:
- /blog/*
- /pricing*
exclude:
type: array
items:
type: string
minLength: 1
maxLength: 200
maxItems: 50
description: URL path patterns to exclude (max 50).
example:
- /legal/*
- /privacy
max_urls:
type: integer
minimum: 1
maximum: 10000
default: 5000
description: Maximum number of sitemap URLs to track (capped at 10,000).
required:
- type
- url
additionalProperties: false
description: >-
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.
title: Sitemap target
MonitorsExtractTarget:
type: object
properties:
type:
type: string
enum:
- extract
url:
type: string
format: uri
description: Root URL to extract structured data from.
example: https://acme.com
schema:
type: object
additionalProperties: {}
description: >-
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.
example:
type: object
properties:
plans:
type: array
items:
type: object
properties:
name:
type: string
price:
type: string
instructions:
type: string
minLength: 1
maxLength: 2000
description: >-
Natural-language instructions guiding which pages and facts to track
and which changes to report.
example: >-
Extract every pricing plan with its monthly price and included
limits.
max_pages:
type: integer
minimum: 1
maximum: 50
default: 10
description: Maximum number of pages to track.
max_depth:
type: integer
minimum: 0
maximum: 10
description: >-
Optional maximum link depth from the starting URL (0 = only the
starting page).
follow_subdomains:
type: boolean
default: false
required:
- type
- url
- instructions
additionalProperties: false
title: Extract target
MonitorsExactChangeDetection:
type: object
properties:
type:
type: string
enum:
- exact
required:
- type
additionalProperties: false
description: >-
Detect exact changes. For page targets, this means visible text diffs.
For sitemap targets, this means URL additions and removals.
title: Exact
MonitorsSemanticChangeDetection:
type: object
properties:
type:
type: string
enum:
- semantic
confidence_threshold:
type: number
minimum: 0
maximum: 1
default: 0.75
required:
- type
additionalProperties: false
description: >-
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).
title: Semantic
MonitorsIntervalSchedule:
type: object
properties:
type:
type: string
enum:
- interval
frequency:
type: integer
minimum: 1
maximum: 525600
description: >-
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).
example: 6
unit:
$ref: '#/components/schemas/MonitorsScheduleUnit'
required:
- type
- frequency
- unit
additionalProperties: false
description: >-
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.
title: Interval
MonitorsWebhookConfig:
type: object
properties:
url:
type: string
format: uri
description: Webhook URL events are delivered to.
example: https://example.com/webhook
events:
type: array
items:
type: string
enum:
- change.detected
- run.completed
minItems: 1
maxItems: 2
uniqueItems: true
description: >-
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.
example:
- change.detected
- run.completed
secret:
type: string
readOnly: true
description: >-
Signing secret used to verify webhook authenticity. Each delivery
includes an `X-Context-Signature: t=,v1=` 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.
example: whsec_8f3a…
required:
- url
additionalProperties: false
MonitorsScheduleUnit:
type: string
enum:
- minutes
- hours
- days
example: hours
responses:
MonitorsUnauthorized:
description: Unauthorized
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Bearer authentication header of the form `Bearer `, where
`` is your api key.
````