> ## 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. # Create a Monitor > Creates a monitor. The request body is a union of the supported target/change detection combinations. The monitor runs immediately after creation to create its initial baseline. 0 Credits 1-10 Credits Per Run Creating a monitor always triggers an immediate first run that captures the **baseline**: the snapshot every later run is compared against. Baseline runs perform no change detection and are billed like any other run. Only `name` and `target` are required. `change_detection` and `schedule` are optional: * **`change_detection`** — inferred from `target` when omitted. `extract` targets default to `semantic`; `sitemap` targets default to `exact`; `page` targets default to `semantic` when `target.instructions` is set and `exact` otherwise. Pass it explicitly only when you want to override defaults (for example, tuning `confidence_threshold` on a semantic monitor). Supported combinations are `page` + `exact`, `page` + `semantic`, `sitemap` + `exact`, and `extract` + `semantic` — anything else returns a `400`, as does a semantic `page` monitor without `instructions` or an exact `page` monitor with `instructions`. * **`schedule`** — defaults to once per day when omitted. Pass an `interval` object to run more or less often; the total interval must be between 10 minutes and 1 year. ## Poll the baseline run The 201 response includes `initial_run_id`: the id of the baseline run that was queued when the monitor was created. Watch [List Monitor Runs](/api-reference/monitors/runs) for this id to confirm the baseline completes before expecting change detection on later runs. `initial_run_id` is `null` in the rare case that the baseline could not be queued immediately at create time — the baseline still runs on the monitor's next scheduled tick, so no action is required. ## OpenAPI ````yaml POST /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: post: tags: - Monitors summary: Create a monitor description: >- Creates a monitor. The request body is a union of the supported target/change detection combinations. The monitor runs immediately after creation to create its initial baseline. operationId: createMonitor requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MonitorsCreateMonitorRequest' examples: page_exact: summary: Exact page monitor value: mode: web name: Acme pricing page target: type: page url: https://acme.com/pricing change_detection: type: exact schedule: type: interval frequency: 6 unit: hours webhook: url: https://example.com/webhook sitemap_exact: summary: Exact sitemap monitor value: mode: web name: Acme sitemap target: type: sitemap url: https://acme.com/sitemap.xml change_detection: type: exact schedule: type: interval frequency: 1 unit: days webhook: url: https://example.com/webhook extract_semantic: summary: Semantic extract monitor value: mode: web name: Acme website positioning target: type: extract url: https://acme.com instructions: >- Extract the product positioning, pricing, packaging, and headline feature claims. max_pages: 10 change_detection: type: semantic schedule: type: interval frequency: 1 unit: days webhook: url: https://example.com/webhook responses: '201': description: Monitor created 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/MonitorsCreateMonitorResponse' '400': $ref: '#/components/responses/MonitorsBadRequest' '401': $ref: '#/components/responses/MonitorsUnauthorized' '403': $ref: '#/components/responses/MonitorsLimitExceeded' 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 monitor = await client.monitors.create({ name: 'Acme pricing page', target: { type: 'page', url: 'https://acme.com/pricing' }, change_detection: { type: 'exact' }, mode: 'web', schedule: { type: 'interval', frequency: 6, unit: 'hours', }, webhook: { url: 'https://example.com/webhook' }, }); console.log(monitor.id); - 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 ) monitor = client.monitors.create( name="Acme pricing page", target={ "type": "page", "url": "https://acme.com/pricing", }, change_detection={ "type": "exact" }, mode="web", schedule={ "type": "interval", "frequency": 6, "unit": "hours", }, webhook={ "url": "https://example.com/webhook" }, ) print(monitor.id) - 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\tmonitor, err := client.Monitors.New(context.TODO(), contextdev.MonitorNewParams{\n\t\tName: \"Acme pricing page\",\n\t\tTarget: contextdev.MonitorNewParamsTargetUnion{\n\t\t\tOfPage: &contextdev.MonitorNewParamsTargetPage{\n\t\t\t\tURL: \"https://acme.com/pricing\",\n\t\t\t},\n\t\t},\n\t\tChangeDetection: contextdev.MonitorNewParamsChangeDetectionUnion{\n\t\t\tOfExact: &contextdev.MonitorNewParamsChangeDetectionExact{},\n\t\t},\n\t\tMode: contextdev.MonitorNewParamsModeWeb,\n\t\tSchedule: contextdev.MonitorNewParamsSchedule{\n\t\t\tType: \"interval\",\n\t\t\tFrequency: 6,\n\t\t\tUnit: \"hours\",\n\t\t},\n\t\tWebhook: contextdev.MonitorNewParamsWebhook{\n\t\t\tURL: \"https://example.com/webhook\",\n\t\t},\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", monitor.ID)\n}\n" - lang: Ruby source: |- require "context_dev" context_dev = ContextDev::Client.new(api_key: "My API Key") monitor = context_dev.monitors.create( name: "Acme pricing page", target: {type: :page, url: "https://acme.com/pricing"} ) puts(monitor) - lang: PHP source: >- monitors->create( name: 'Acme pricing page', target: [ 'type' => 'page', 'url' => 'https://acme.com/pricing', 'instructions' => 'Report pricing or plan availability changes. Ignore counters, timestamps, testimonials, and navigation.', 'normalizeWhitespace' => true, ], changeDetection: ['type' => 'exact'], mode: 'web', schedule: ['frequency' => 6, 'type' => 'interval', 'unit' => 'hours'], tags: ['pricing', 'competitor'], webhook: [ 'url' => 'https://example.com/webhook', 'events' => ['change.detected', 'run.completed'], ], ); var_dump($monitor); } catch (APIException $e) { echo $e->getMessage(); } - lang: CLI source: |- context-dev monitors create \ --api-key 'My API Key' \ --name 'Acme pricing page' \ --target '{type: page, url: https://acme.com/pricing}' components: schemas: MonitorsCreateMonitorRequest: type: object properties: mode: $ref: '#/components/schemas/MonitorsMode' name: type: string minLength: 1 maxLength: 200 example: Acme pricing monitor 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 target: $ref: '#/components/schemas/MonitorsTarget' change_detection: $ref: '#/components/schemas/MonitorsChangeDetection' schedule: $ref: '#/components/schemas/MonitorsSchedule' webhook: $ref: '#/components/schemas/MonitorsNullableWebhookConfig' required: - name - target additionalProperties: false title: Create monitor request description: >- Creates a web monitor. `mode` is the constant `web`; the behavior is described by `target` (page, sitemap, or extract) and `change_detection` (exact or semantic). Supported combinations: page + exact, page + semantic, sitemap + exact, extract + semantic. `change_detection` is optional; page targets with `instructions` infer semantic detection, while page targets without them infer exact detection. Other targets default to their supported detection type. `schedule` is optional and defaults to once per day. MonitorsCreateMonitorResponse: allOf: - $ref: '#/components/schemas/MonitorsMonitor' - type: object required: - initial_run_id properties: initial_run_id: type: - string - 'null' description: >- The baseline run queued by this create call, or null if it could not be queued immediately (in which case the baseline runs on the next scheduled tick). Poll GET /monitors/{monitor_id}/runs/{run_id}. example: run_123 title: Create monitor response description: >- A newly created monitor plus `initial_run_id`, the id of the baseline run queued at creation. 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' 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' 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 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. MonitorsScheduleUnit: type: string enum: - minutes - hours - days example: hours 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 responses: MonitorsBadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-RateLimit-Limit: $ref: '#/components/headers/RateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/RateLimitReset' 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' MonitorsLimitExceeded: description: >- Monitor limit for the account reached (error_code MONITOR_LIMIT_EXCEEDED) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: 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 `, where `` is your api key. ````