> ## 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.0.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: Monitors
description: >-
Monitor pages, sitemaps, and extracted website data for exact or semantic
changes. The change.detected webhook payload is documented by the
MonitorsChangeDetectedWebhookPayload schema.
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:
- $ref: '#/components/parameters/MonitorsSearchQuery'
- $ref: '#/components/parameters/MonitorsSearchBy'
- $ref: '#/components/parameters/MonitorsSearchType'
- $ref: '#/components/parameters/MonitorsTargetTypeFilter'
- $ref: '#/components/parameters/MonitorsChangeDetectionTypeFilter'
- $ref: '#/components/parameters/MonitorsMonitorStatusFilter'
- $ref: '#/components/parameters/MonitorsTagsFilter'
- $ref: '#/components/parameters/MonitorsTagFilter'
- $ref: '#/components/parameters/MonitorsLimit'
- $ref: '#/components/parameters/MonitorsCursor'
responses:
'200':
description: A paginated list of monitors
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: 'q',
searchBy: ['name'],
searchType: 'exact',
status: 'active',
tag: 'tag',
tags: ['string'],
targetType: 'page',
);
var_dump($monitors);
} catch (APIException $e) {
echo $e->getMessage();
}
- lang: CLI
source: |-
context-dev monitors list \
--api-key 'My API Key'
components:
parameters:
MonitorsSearchQuery:
name: q
in: query
required: false
schema:
type: string
maxLength: 200
description: Free-text search term, matched against the fields named in `search_by`.
example: pricing
MonitorsSearchBy:
name: search_by
in: query
required: false
style: form
explode: false
schema:
type: array
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
MonitorsSearchType:
name: search_type
in: query
required: false
schema:
type: string
enum:
- exact
- prefix
default: prefix
description: >-
`prefix` for as-you-type prefix matching (default), `exact` for
full-token matching.
MonitorsTargetTypeFilter:
name: target_type
in: query
required: false
schema:
$ref: '#/components/schemas/MonitorsTargetType'
MonitorsChangeDetectionTypeFilter:
name: change_detection_type
in: query
required: false
schema:
$ref: '#/components/schemas/MonitorsChangeDetectionType'
MonitorsMonitorStatusFilter:
name: status
in: query
required: false
schema:
$ref: '#/components/schemas/MonitorsMonitorStatus'
MonitorsTagsFilter:
name: tags
in: query
required: false
style: form
explode: false
schema:
type: array
items:
type: string
description: >-
Comma-separated list of tags to filter by (matches monitors having any
of them).
example: pricing,competitor
MonitorsTagFilter:
name: tag
in: query
required: false
schema:
type: string
description: Filter to items that have this tag.
example: pricing
MonitorsLimit:
name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 25
MonitorsCursor:
name: cursor
in: query
required: false
schema:
type: string
schemas:
MonitorsListMonitorsResponse:
type: object
required:
- data
- has_more
- next_cursor
properties:
data:
type: array
items:
$ref: '#/components/schemas/MonitorsMonitor'
has_more:
type: boolean
next_cursor:
type: string
nullable: true
additionalProperties: false
MonitorsTargetType:
type: string
enum:
- page
- sitemap
- extract
MonitorsChangeDetectionType:
type: string
enum:
- exact
- semantic
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`.
MonitorsMonitor:
type: object
title: Monitor
description: >-
A web monitor. `mode` is the constant `web`; behavior is described by
`target` (page/sitemap/extract) and `change_detection` (exact/semantic).
required:
- mode
- id
- name
- target
- change_detection
- schedule
- status
- created_at
- updated_at
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
format: date-time
nullable: true
last_change_at:
type: string
format: date-time
nullable: true
next_run_at:
type: string
format: date-time
nullable: true
description: When the next scheduled run is due.
last_error:
nullable: true
description: >-
Error from the most recent failed run; null when the last run
succeeded.
allOf:
- $ref: '#/components/schemas/MonitorsRunError'
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
description: >-
User-defined tags for grouping and filtering monitors and their
changes.
example:
- pricing
- competitor
baseline:
nullable: true
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).
oneOf:
- $ref: '#/components/schemas/MonitorsPageBaseline'
- $ref: '#/components/schemas/MonitorsSitemapBaseline'
- $ref: '#/components/schemas/MonitorsExtractBaseline'
additionalProperties: false
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
- INSUFFICIENT_PERMISSIONS
- TIMEOUT_EXCEEDS_MAXIMUM
- WEBSITE_ACCESS_ERROR
- EXTERNAL_PROVIDER_ERROR
- INPUT_VALIDATION_ERROR
- REQUEST_TIMEOUT
description: Error code indicating the type of error
key_metadata:
$ref: '#/components/schemas/KeyMetadata'
MonitorsMode:
type: string
title: Monitor mode
enum:
- web
description: >-
Top-level monitor category. Always `web` today; the concrete behavior is
described by `target` and `change_detection`.
MonitorsTarget:
description: Discriminated union describing what the monitor watches.
oneOf:
- $ref: '#/components/schemas/MonitorsPageTarget'
- $ref: '#/components/schemas/MonitorsSitemapTarget'
- $ref: '#/components/schemas/MonitorsExtractTarget'
discriminator:
propertyName: type
mapping:
page:
$ref: '#/components/schemas/MonitorsPageTarget'
sitemap:
$ref: '#/components/schemas/MonitorsSitemapTarget'
extract:
$ref: '#/components/schemas/MonitorsExtractTarget'
MonitorsChangeDetection:
description: Discriminated union describing how changes are detected.
oneOf:
- $ref: '#/components/schemas/MonitorsExactChangeDetection'
- $ref: '#/components/schemas/MonitorsSemanticChangeDetection'
discriminator:
propertyName: type
mapping:
exact:
$ref: '#/components/schemas/MonitorsExactChangeDetection'
semantic:
$ref: '#/components/schemas/MonitorsSemanticChangeDetection'
MonitorsSchedule:
description: >-
Discriminated union describing how the monitor is scheduled. Only
`interval` is supported today; `cron` and `exact_time` are reserved for
future use.
oneOf:
- $ref: '#/components/schemas/MonitorsIntervalSchedule'
discriminator:
propertyName: type
mapping:
interval:
$ref: '#/components/schemas/MonitorsIntervalSchedule'
MonitorsNullableWebhookConfig:
nullable: true
allOf:
- $ref: '#/components/schemas/MonitorsWebhookConfig'
MonitorsRunError:
type: object
required:
- code
- message
properties:
code:
type: string
example: fetch_failed
message:
type: string
example: The target URL could not be fetched.
additionalProperties: false
MonitorsPageBaseline:
type: object
title: Page baseline
description: >-
Current baseline of a `page` monitor: the visible page text as last
observed.
required:
- text
- captured_at
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.
additionalProperties: false
MonitorsSitemapBaseline:
type: object
title: Sitemap baseline
description: >-
Current baseline of a `sitemap` monitor: the normalized URL set as last
observed.
required:
- urls
- url_count
- captured_at
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.
additionalProperties: false
MonitorsExtractBaseline:
type: object
title: Extract baseline
description: >-
Current baseline of an `extract` monitor: the pages it tracks and the
structured data as last extracted.
required:
- data
- urls_analyzed
- captured_at
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.
additionalProperties: false
KeyMetadata:
type: object
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.
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
MonitorsPageTarget:
type: object
title: Page target
description: Watch a single web page.
required:
- type
- url
properties:
type:
type: string
enum:
- page
url:
type: string
format: uri
example: https://acme.com/pricing
normalize_whitespace:
type: boolean
default: true
description: Normalize whitespace before comparing or analyzing text.
additionalProperties: false
MonitorsSitemapTarget:
type: object
title: Sitemap target
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.
required:
- type
- url
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
description: URL path patterns to include.
example:
- /blog/*
- /pricing*
exclude:
type: array
items:
type: string
description: URL path patterns to exclude.
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).
additionalProperties: false
MonitorsExtractTarget:
type: object
title: Extract target
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 against the monitor's instructions.
The tracked page set is refreshed by a periodic re-discovery crawl.
required:
- type
- url
- instructions
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: true
description: >-
JSON Schema describing the data you care about. It guides which
pages are selected for tracking and gives the change judge context
on what matters. 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
additionalProperties: false
MonitorsExactChangeDetection:
type: object
title: Exact
description: >-
Detect exact changes. For page targets, this means visible text diffs.
For sitemap targets, this means URL additions and removals.
required:
- type
properties:
type:
type: string
enum:
- exact
additionalProperties: false
MonitorsSemanticChangeDetection:
type: object
title: Semantic
description: >-
Detect meaning-level changes to the extracted data, ignoring cosmetic or
paraphrase-only differences. What is watched is determined by the
extract target's `schema` and `instructions`.
required:
- type
properties:
type:
type: string
enum:
- semantic
confidence_threshold:
type: number
minimum: 0
maximum: 1
default: 0.75
additionalProperties: false
MonitorsIntervalSchedule:
type: object
title: Interval
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.
required:
- type
- frequency
- unit
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'
additionalProperties: false
MonitorsWebhookConfig:
type: object
required:
- url
properties:
url:
type: string
format: uri
description: Webhook URL called when a change is detected.
example: https://example.com/webhook
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…
additionalProperties: false
MonitorsScheduleUnit:
type: string
enum:
- minutes
- hours
- days
example: hours
responses:
MonitorsUnauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````