How it works
Extract is an optional parameter onPOST /v1/read. The scrape pipeline runs as usual, then the extracted markdown is sent to an LLM with your schema for structured extraction.
extracted field appears in the response alongside markdown, html, and other standard fields. If extraction fails, the scrape result is still returned with an error in metadata.extraction.extractionError.
Schema formats
JSON Schema (full)
Standard JSON Schema with types, descriptions, and nested objects:Shorthand
A simpler format where keys map directly to type names:string, number, integer, boolean, array, object.
Prompt-only
No schema, just a natural language instruction. Returns freeform JSON:Prompt + Schema
Combine both for maximum control. The prompt guides the LLM while the schema enforces structure:Response shape
Null handling
If a field in your schema does not exist on the page, Reader returnsnull for that field. It will never hallucinate values that are not present in the content.
Credits
Extract adds 2 credits on top of the scrape cost:
If the scrape succeeds but extraction fails, the full cost (scrape + extract) is still charged because the LLM call was attempted.
Limitations
- Scrape mode only. Extract is not supported for batch or crawl operations.
- Token limit. Page content is capped at 30,000 tokens before being sent to the LLM. Long pages are intelligently truncated (70% from the beginning, 30% from the end).
- No caching. Extraction always runs fresh, even if the scrape result is cached. Cached scrape responses do not include
extracted. - Validation retry. If the LLM output does not match your schema, Reader retries once with additional context about the validation error.
Error handling
Extract never fails the entire request. If the LLM call fails (timeout, rate limit, invalid response), the scrape result is still returned withextracted: null and an error in metadata.extraction.extractionError:

