--- title: "Extract structured data" method: POST path: "/web/extract" tags: ["Web Extraction"] --- # Extract structured data `POST /web/extract` ## Request - Base URL: `https://api.context.dev/v1` - URL: `https://api.context.dev/v1/web/extract` - Auth: HTTP bearer Extract website data using your JSON Schema and instructions. ## Request body - object - `url` string, uri, required: The starting website URL to crawl and extract from. Must include http:// or https://. - `schema` object, required: JSON Schema (not an example object) for the returned object. Image fields include relevant page image references. - `instructions` string: Optional extraction guidance, such as which facts to prioritize or how to interpret fields in the schema. - `factCheck` boolean: Require facts stated on the page. Unsupported fields become null or empty. - `followSubdomains` boolean: When true, follow links on subdomains of the starting URL's domain. - `maxPages` integer: Maximum number of pages to analyze for extraction. Hard cap: 50. Defaults to 5. - `maxDepth` integer: Optional maximum link depth from the starting URL (0 = only the starting page). If omitted, there is no crawl depth limit. - `pdf` object: PDF handling. `start`/`end` limit parsing to an inclusive, 1-based page range. - `shouldParse` boolean: When true, PDF pages are fetched and parsed. When false, PDF pages are skipped. - `start` integer: First 1-based PDF page to parse. - `end` integer: Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must be >= start. - `includeFrames` boolean: When true, iframe contents are included in Markdown before extraction. - `maxAgeMs` integer, nullable: Return cached scrape results if a prior scrape for the same parameters is younger than this many milliseconds. Defaults to 7 days (604800000 ms). - `waitForMs` integer, nullable: Optional browser wait time in milliseconds after initial page load for each crawled page. - `settleAnimations` boolean: Wait briefly for CSS animations and transitions to settle before reading each page. - `actions` WebScrapeAction[], nullable: Browser steps before page discovery. Requires a paid plan; defaults the crawl budget to 110000 ms. - 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. - `do` 'wait', required: Use `wait` to pause for a fixed duration. - `timeMs` integer, required: Time to pause in milliseconds before the next action. - WebScrapePerformAction: Resolve and perform one natural-language browser action. - `do` 'perform', required: Use `perform` for a plain-language browser instruction. - `action` string, required: One browser instruction, such as clicking a button or entering text. - WebScrapeScrollAction: Scroll the page or a selected scrollable container, waiting adaptively for content and dimensions to settle after each iteration. - `do` 'scroll', required: Use `scroll` to move through the page or a container. - `direction` 'up' | 'down' | 'left' | 'right': Direction to scroll. Defaults to down. - `amount` union: Pixels per scroll, one visible viewport, or the current scroll boundary. Defaults to viewport. - integer - 'viewport' | 'max' - `container` string: CSS selector for the first matching scroll container. Defaults to the page. - `maxScrolls` integer: Maximum scroll iterations. Stops early when scrolling and scrollable extent stop changing. Defaults to 1. - `stopAfterMs` integer: Soft time budget for the crawl in milliseconds. Min: 10000 (10s). Max: 110000 (110s). Defaults to 80000 (80s), or 110000 (110s) when browser actions are provided. - `timeoutOpts` PartialTimeout: Request deadline and what to return when it passes. - `milliseconds` integer, required: Deadline in milliseconds. - `behavior` 'fail' | 'return-partial': "fail" returns 408 at the deadline. "return-partial" returns available results; inspect the response’s partial flag. - `zdr` 'enabled' | 'disabled': `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR. - `tags` string[]: Labels for filtering usage in the dashboard. ## Response `200` Successful response - object - `partial` boolean: True when the timeout ended processing and this response contains only usable results completed so far. Unfinished results are omitted. - `status` string, required: Always `ok` on success. - `url` string, required: The starting URL that was analyzed - `urls_analyzed` string[], required: List of URLs whose Markdown was used for extraction - `data` object, required: Extracted data matching the request schema - `metadata` object, required - `numUrls` integer, required - `maxCrawlDepth` integer, required - `numSucceeded` integer, required - `numFailed` integer, required - `numSkipped` integer, required - `numBlocked` integer, required: Number of crawled pages excluded because they were anti-bot challenges, error pages, or parked-domain placeholders. - `actionsApplied` object[]: One verified outcome per requested browser action, in request order. - `instruction` string, required - `status` 'applied' | 'failed' | 'skipped', required: Applied means the requested page state was visibly verified. Failed means it was not verified. Skipped means it was not attempted. - `method` string - `targetDescription` string - `completionEvidence` string: Visible page evidence used to verify an applied action. - `error` string - `durationMs` number - `cache_metadata` CacheMetadata, required: Whether this response came from cache. - `status` 'hit' | 'miss' | 'zdr', required: Whether the response was served from cache, required fresh work, or honored zero-data-retention cache bypass. - `age_ms` integer, required: Age of the cached data in milliseconds. Zero for miss and zdr responses. - `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 - Invalid URL, schema, or inaccessible website - `401`: Unauthorized - Invalid or missing API key - `402`: Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401. - `403`: API key permissions or organization settings do not allow this request. - `408`: Request timeout - `429`: Rate limit exceeded. Organization concurrency rejections include structured error_data and subscription settings; follow Retry-After before retrying. - `500`: Internal server error ## Changes - **2026-10-21** `61627728926b`: 5 warning - 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 `402` - 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 `408` - …1 more - **2026-10-19** `4ddcf49b9fe5`: 6 info - added the non-success response with the status `402` - 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 `408` status - …2 more - **2026-10-16** `2125f3e94e52`: 1 info - endpoint added [Operation history](https://skmtc.dev/context/apis/brand-api/changes/web/extract/post.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)