# Extracto API > Extracto turns any public web page into clean markdown or structured JSON with a > single API call. Render a page (JavaScript included, with an anti-bot stealth > fallback), extract fields matching a schema you describe, or discover a site's URLs. This file is a complete reference written for language models. Paste it into your AI assistant to have it write or debug an Extracto integration. - Base URL: https://app.getextracto.dev - Interactive docs: https://app.getextracto.dev/docs - OpenAPI spec: https://app.getextracto.dev/openapi.json - MCP server: https://mcp.getextracto.dev ## Authentication Every request needs an API key, sent as a bearer token. Create and manage keys in the dashboard. Keys look like `exa_live_...`. ``` Authorization: Bearer exa_live_... ``` ## Endpoints Three operations share the same renderer: - `POST /v1/scrape`: render one page into markdown / html / text / links (and optionally structured JSON). Default is clean markdown. - `POST /v1/extract`: render one page and return JSON validated against your schema. - `POST /v1/map`: discover a site's page URLs (robots.txt + sitemap + on-page links). ### POST /v1/scrape Request body (`application/json`): - `url` (string, required): the public HTTPS URL of the page to render. - `formats` (string[], optional): any of `markdown`, `html`, `text`, `links`, `json`. Defaults to `["markdown"]`. Include `"json"` to also run the structured extractor (then `schema` is required). - `schema` (object, optional): required only with the `"json"` format; same shorthand grammar as /v1/extract. Response (`200`, `application/json`): - `data` (object): one field per requested format: `markdown`, `html`, `text`, `links` (string[]), `json` (object). Each field is present only when its format was requested. - `extracted_in_ms` (integer), `cached` (boolean). - `credits_used` (integer): see the credit table below; `0` on a cache hit. - `engine` (string): `"cf"` (standard) or `"stealth"` (anti-bot) renderer that served the page. ```json { "url": "https://example.com/blog/launch", "formats": [ "markdown", "links" ] } ``` ```json { "data": { "markdown": "# Launch\n\nWe shipped today. Read the [notes](https://example.com/notes).", "links": [ "https://example.com/notes", "https://example.com/pricing" ] }, "extracted_in_ms": 1840, "cached": false, "credits_used": 1, "engine": "cf" } ``` ### POST /v1/extract Request body (`application/json`): - `url` (string, required): the public HTTPS URL of the page to extract from. - `schema` (object, required): the shape you want back (see "Schema language"). Response (`200`, `application/json`): - `data` (object): mirrors your `schema` exactly; any field that cannot be found is `null`. - `extracted_in_ms` (integer): server-side extraction time. - `cached` (boolean): whether the result was served from cache. - `credits_used` (integer): quota credits this call consumed (see the credit table below). ### POST /v1/map Request body (`application/json`): - `url` (string, required): the public HTTPS URL of the site to map. - `limit` (integer, optional): max URLs to return. Default 100, max 5000. - `includeSubdomains` (boolean, optional): include subdomains of the registrable domain. Default false. - `search` (string, optional): keep only URLs containing this substring. Response (`200`, `application/json`): `links` (string[], deduped, same-domain, SSRF-checked), `cached`, `credits_used` (flat 1 per call), `engine` (always `"cf"`). No LLM is involved. ```json { "url": "https://example.com", "limit": 100 } ``` ```json { "links": [ "https://example.com/", "https://example.com/pricing", "https://example.com/blog/launch", "https://example.com/docs" ], "cached": false, "credits_used": 1, "engine": "cf" } ``` ## Schema language The `schema` field is a shorthand. Each value is one of: - a type literal: "string", "number", "boolean", "array", "object" - an array with a single descriptor for a list: `["string"]` or `[{ "name": "string" }]` - a nested object for a sub-structure: `{ "name": "string", "rating": "number" }` The response `data` mirrors the schema key-for-key. Limits: at most 15 top-level fields and 2048 bytes per schema. ## Reliability: examples and retries Pass an optional `examples` array (up to 3) of correctly shaped outputs to anchor the FORMAT the model returns (decimal style, units, date format). Each `example.output` must match your `schema`. The extractor also retries automatically on a transient model fault, so a single blip does not surface as a failure. ```json { "url": "https://example.com/product/123", "schema": { "title": "string", "price": "number", "in_stock": "boolean", "tags": [ "string" ], "brand": { "name": "string" } }, "examples": [ { "url": "https://example.com/product/9", "output": { "title": "Sample Widget", "price": 12.5, "in_stock": true, "tags": [ "sample" ], "brand": { "name": "SampleCo" } } } ] } ``` ## Async jobs For heavy or anti-bot pages, submit a job instead of blocking on the synchronous call. `POST /v1/jobs`: same body as `/v1/extract`, plus an optional `webhook_url`. ```json { "url": "https://example.com/product/123", "schema": { "title": "string", "price": "number", "in_stock": "boolean", "tags": [ "string" ], "brand": { "name": "string" } }, "webhook_url": "https://your-app.com/extracto/callback" } ``` Returns `202 Accepted` immediately, with a `Location` header pointing at the job resource, and a body: ```json { "id": "4b2e2b1a-9f1e-4a1c-bb3a-1d2e3f4a5b6c", "status": "pending", "status_url": "https://app.getextracto.dev/v1/jobs/4b2e2b1a-9f1e-4a1c-bb3a-1d2e3f4a5b6c" } ``` Send an optional `Idempotency-Key` header (any unique string per logical request) so a network retry replays the original job instead of creating a second one. The same header works on the synchronous `POST /v1/scrape` and `POST /v1/extract` calls: a retry replays the original response (including `credits_used`) instead of re-running and re-charging the work. `GET /v1/jobs/{id}`: the job, with `result` once it succeeds. `GET /v1/jobs` lists your recent jobs. `DELETE /v1/jobs/{id}` cancels a still-pending job. ```json { "id": "4b2e2b1a-9f1e-4a1c-bb3a-1d2e3f4a5b6c", "status": "success", "url": "https://example.com/product/123", "result": { "title": "Acme Widget", "price": 19.99, "in_stock": true, "tags": [ "durable", "blue" ], "brand": { "name": "Acme" } }, "error": null, "credits_used": 5, "created_at": 1700000000000, "completed_at": 1700000004000 } ``` ### Webhook delivery and signature When a job finishes, Extracto POSTs the result to your `webhook_url` (or the active endpoints configured in the dashboard). The body is: ```json { "type": "job.completed", "job": { "id": "4b2e2b1a-9f1e-4a1c-bb3a-1d2e3f4a5b6c", "status": "success", "url": "https://example.com/product/123", "result": { "title": "Acme Widget", "price": 19.99, "in_stock": true, "tags": [ "durable", "blue" ], "brand": { "name": "Acme" } }, "error": null, "credits_used": 5, "completed_at": 1700000004000 } } ``` Each delivery carries an `X-Extracto-Signature: t=,v1=` header. Verify it by recomputing HMAC-SHA256 over `${t}.${rawBody}` with your endpoint secret and comparing in constant time (the same scheme Stripe uses). Reject deliveries whose timestamp is outside a few minutes to prevent replay. ## Examples ### Scrape a page to markdown (curl) ```bash curl -X POST https://app.getextracto.dev/v1/scrape \ -H "Authorization: Bearer exa_live_..." \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com/blog/launch","formats":["markdown","links"]}' ``` ### Extract structured JSON (curl) ```bash curl -X POST https://app.getextracto.dev/v1/extract \ -H "Authorization: Bearer exa_live_..." \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com/product/123","schema":{"title":"string","price":"number","tags":["string"]}}' ``` ### Extract structured JSON (JavaScript / TypeScript) ```ts const res = await fetch("https://app.getextracto.dev/v1/extract", { method: "POST", headers: { Authorization: `Bearer ${process.env.EXTRACTO_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "url": "https://example.com/product/123", "schema": { "title": "string", "price": "number", "tags": [ "string" ] } }), }); const data = await res.json(); ``` ### Extract structured JSON (Python) ```python import os import requests res = requests.post( "https://app.getextracto.dev/v1/extract", headers={"Authorization": f"Bearer {os.environ['EXTRACTO_API_KEY']}"}, json={ "url": "https://example.com/product/123", "schema": { "title": "string", "price": "number", "tags": [ "string" ] } }, ) data = res.json() ``` ### Map a site (Python) ```python import os import requests res = requests.post( "https://app.getextracto.dev/v1/map", headers={"Authorization": f"Bearer {os.environ['EXTRACTO_API_KEY']}"}, json={ "url": "https://example.com", "limit": 100 }, ) data = res.json() ``` ### Example extract request body ```json { "url": "https://example.com/product/123", "schema": { "title": "string", "price": "number", "in_stock": "boolean", "tags": [ "string" ], "brand": { "name": "string" } } } ``` ### Example extract 200 response ```json { "data": { "title": "Acme Widget", "price": 19.99, "in_stock": true, "tags": [ "durable", "blue" ], "brand": { "name": "Acme" } }, "extracted_in_ms": 5421, "cached": false, "credits_used": 5 } ``` ## MCP server (for AI agents) Extracto ships a hosted Model Context Protocol server so an AI assistant can scrape, extract, map and check jobs as native tools, reusing the same pipeline as the REST API. Endpoint: ``` https://mcp.getextracto.dev ``` Authenticate with the same `exa_live_...` API key as a bearer token (no OAuth). Tools: - `scrape_page`: read ONE page as markdown / text / html / links. - `extract_data`: get specific structured fields back as JSON (needs a schema). - `map_site`: discover the URLs of a site (use before scraping MANY pages). - `get_job`: check the status or result of an async job. Add it in Claude Code: ```bash claude mcp add --transport http extracto https://mcp.getextracto.dev \ --header "Authorization: Bearer exa_live_..." ``` Add it in Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`): ```json { "mcpServers": { "extracto": { "url": "https://mcp.getextracto.dev", "headers": { "Authorization": "Bearer exa_live_..." } } } } ``` ## Migrating from Firecrawl If you already call Firecrawl, switching is mostly a base-URL change. Extracto exposes happy-path-compatible routes under `/fc/v1/` that accept Firecrawl-shaped requests and return the Firecrawl envelope `{ "success": true, "data": { ... } }`: - `POST /fc/v1/scrape` maps to `/v1/scrape`. It honors `formats` and `jsonOptions.schema` (these change the output); other Firecrawl tuning fields (`onlyMainContent`, `includeTags`/`excludeTags`, `waitFor`, etc.) are accepted but ignored, so an existing payload keeps working without erroring. - `POST /fc/v1/map` maps to `/v1/map` (honors `url`, `limit`, `search`, `includeSubdomains`). Point your Firecrawl client's base URL at `https://app.getextracto.dev/fc` and use your Extracto `exa_live_...` key as the bearer token. For new code prefer the native `/v1/` routes: they return the `{ "error": { "code", "message" } }` envelope and the credit table below. The `/fc/` surface is a compatibility shim covering the common scrape/map subset, not every Firecrawl field. ## Quotas and billing Each successful call consumes credits from your monthly quota. The cost depends only on the operation, not on which engine served the page: a request that needs the anti-bot `stealth` engine (residential proxy + JS rendering) costs exactly the same as one served by the standard Cloudflare renderer (`cf`). Since you cannot know in advance whether a URL needs anti-bot, the price is flat so it is never a surprise. The `engine` field still reports which renderer ran, for transparency. | Operation | Credits | | --- | --- | | `scrape` (markdown/html/text/links, no LLM) | 1 | | `extract` (render + structured JSON via LLM) | 5 | | `map` (discover a site's URLs) | 1 | | cache hit (any operation) | 0 | | any failure (non-2xx) | 0 | Two cases never cost anything: a cache hit (you already paid for the first fetch) and any failure (a non-2xx response). Every response reports its exact charge in `credits_used` and sets the `X-Credits-Used` / `X-Credits-Remaining` headers. Plans: - Free (free): 100 pages one-time, up to 1 requests/second. - Hobby ($14/month): 5,000 pages/month, up to 5 requests/second. - Standard ($69/month): 30,000 pages/month, up to 20 requests/second. - Growth ($299/month): 120,000 pages/month, up to 50 requests/second. When the monthly quota is exhausted, calls return `402 quota_exceeded` until the period resets or you upgrade. ## Errors Every error response uses the same envelope: ```json { "error": { "code": "string", "message": "string" } } ``` Some errors add fields: `429` responses include `retry_after_seconds`, and `402` includes an `upgrade` hint. Full list of codes: - `bad_request` (HTTP 400): Request body must be valid JSON. - `unauthorized` (HTTP 401): Provide a valid API key as `Authorization: Bearer exa_live_...`. - `quota_exceeded` (HTTP 402): Monthly page quota exhausted for the current period. - `rate_limited` (HTTP 429): Too many requests. Slow down and retry shortly. - `ip_rate_limited` (HTTP 429): Daily limit reached for this network on the free plan. Upgrade for higher limits. - `idempotency_conflict` (HTTP 422): This Idempotency-Key was already used for a request with a different body. - `idempotency_in_flight` (HTTP 409): A request with this Idempotency-Key is still in progress. Retry shortly. - `internal_error` (HTTP 500): An unexpected error occurred. - `url_invalid` (HTTP 422): The url must be a valid public HTTPS URL. - `blocked_domain` (HTTP 422): This domain is not supported (authentication-walled or restricted). - `schema_invalid` (HTTP 422): The schema is malformed or uses an unsupported type. - `schema_too_large` (HTTP 422): The schema exceeds the maximum size. - `schema_too_many_fields` (HTTP 422): The schema has too many top-level fields. - `schema_injection` (HTTP 422): The schema contains a disallowed value. - `timeout` (HTTP 503): The extraction timed out. - `browser_error` (HTTP 422): The page could not be rendered. - `browser_blocked` (HTTP 422): The page is protected by anti-bot and could not be retrieved. - `browser_unavailable` (HTTP 503): The rendering service is temporarily at capacity. Retry after a short delay. - `upstream_error` (HTTP 422): The target page returned an error status and could not be rendered. - `model_error` (HTTP 503): The extraction model failed. - `schema_mismatch` (HTTP 422): Extracted data did not match the requested schema. ## Integration tips - Always use HTTPS URLs. Non-HTTPS, private, or authentication-walled hosts are rejected with `url_invalid` or `blocked_domain`. - On `429`, back off and retry using `retry_after_seconds`. - On `402`, stop and upgrade the plan; retrying will not help until the period resets. - Treat `null` fields in `data` as "not found on the page", not as an error.