> ## 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.
# Retrieve a Monitor
> Fetch a monitor's full configuration, status, schedule, and current baseline by ID.
0 Credits
## OpenAPI
````yaml GET /monitors/{monitor_id}
openapi: 3.1.0
info:
title: Context.dev API
description: API for retrieving context data from any website
version: 1.0.0
servers:
- url: https://api.context.dev/v1
security: []
tags:
- name: Webhooks
description: Inspect and retry webhook deliveries. These endpoints cost no credits.
- name: Logs
description: >-
Read your organization's API request logs to debug failed calls. These
endpoints cost no credits and use a separate rate limit.
- 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: News
description: >-
Search live first-party RSS and free historical news data by company
identity.
- name: Answers
description: Answer a research task from the live web in the JSON shape you ask for.
paths:
/monitors/{monitor_id}:
get:
tags:
- Monitors
summary: Get a monitor
operationId: getMonitor
parameters:
- schema:
type: string
example: mon_123
required: true
name: monitor_id
in: path
responses:
'200':
description: Monitor
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
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/MonitorsMonitor'
'401':
$ref: '#/components/responses/MonitorsUnauthorized'
'404':
$ref: '#/components/responses/MonitorsNotFound'
security:
- bearerAuth: []
components:
headers:
RequestId:
description: >-
Unique id of this API call, sent on every response and mirrored as
request_id in JSON bodies. Quote it when contacting support.
schema:
type: string
format: uuid
RateLimitLimit:
description: Maximum requests per minute.
schema:
type: integer
minimum: 1
RateLimitRemaining:
description: Requests remaining in the current minute.
schema:
type: integer
minimum: 0
RateLimitReset:
description: Unix timestamp in seconds when the rate limit resets.
schema:
type: integer
schemas:
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).
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.
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
- TIMEOUT_TOO_SHORT_FOR_WAIT
- 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
- DELIVERY_IN_PROGRESS
- DELIVERY_ALREADY_DELIVERED
- DELIVERY_EXPIRED
- DELIVERY_CANCELLED
description: Error code indicating the type of error
required_permission:
type: string
enum:
- logs:read
- data:execute
- monitors:read
- monitors:write
- batches:read
- batches:write
- webdbs:read
- webdbs:write
description: >-
Permission required for this request when error_code is
INSUFFICIENT_PERMISSIONS. Manage (write) also grants read access to
the same resource group.
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
request_id:
$ref: '#/components/schemas/RequestId'
required:
- request_id
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.
include_selectors:
type: array
items:
type: string
minLength: 1
maxLength: 2048
maxItems: 50
description: >-
CSS selectors defining the HTML regions to monitor. Matching
subtrees are combined in document order before text extraction,
instead of automatic main-content selection. Omit or pass an empty
array to use automatic main-content extraction. If the filtered page
has no usable text, the run fails without replacing the baseline.
Changing these selectors creates a new baseline.
example:
- '#attraction-details'
exclude_selectors:
type: array
items:
type: string
minLength: 1
maxLength: 2048
maxItems: 50
description: >-
CSS selectors for HTML regions to remove before text extraction.
Applied after include_selectors; exclusion takes precedence when an
element matches both. Omit or pass an empty array to apply no
explicit exclusions. Changing these selectors creates a new
baseline.
example:
- .carousel
- '[id^="TA_"]'
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. Slack incoming webhook URLs are
automatically formatted as Slack messages.
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
retry:
$ref: '#/components/schemas/WebhookRetry'
secret:
type: string
readOnly: true
description: >-
Signing secret used to verify webhook authenticity. Omitted unless
the API key has monitors:write permission or full access. 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
KeyMetadata:
type: object
properties:
credits_consumed:
type: integer
description: Credits used by this request.
credits_remaining:
type: integer
description: Credits remaining for your organization.
required:
- credits_consumed
- credits_remaining
description: Credit usage, included whenever a valid API key is provided.
RequestId:
type: string
format: uuid
description: >-
Unique id of this API call, also sent in the X-Request-Id response
header. Quote it when contacting support about a failed request.
example: 3f1c2a6e-8b4d-4c1e-9f0a-2d7b5e6c8a91
MonitorsScheduleUnit:
type: string
enum:
- minutes
- hours
- days
example: hours
WebhookRetry:
type: object
properties:
delays_seconds:
type: array
items:
type: integer
minimum: 1
maximum: 86400
maxItems: 10
description: >-
Retry delays in seconds, totaling at most 72 hours. Use [] to
disable automatic retries.
example:
- 30
- 300
- 3600
additionalProperties: false
description: Webhook retry settings. Use {} for the default schedule.
example:
delays_seconds:
- 10
- 60
- 300
- 1800
- 7200
- 21600
- 57600
responses:
MonitorsUnauthorized:
description: Unauthorized
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
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'
MonitorsNotFound:
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
X-RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Bearer authentication header of the form `Bearer `. Keys have
full access by default.
````