Extracting Structured Data

Extraction modes

The extract field is available on Fetch, Crawl, and Interact. Always pair it with "output": ["json"] — the extracted data is returned in outputs.json.

`mode: "schema"` — described-field extraction

Describe the fields you want in plain English. By default the API uses an LLM to locate and extract them if a provider is configured, falling back to a heuristic extractor otherwise. Pass "engine": "llm" to require the LLM and fail with llm_unavailable instead of silently falling back, or "engine": "heuristic" to skip the LLM entirely.

{
  "url": "https://news.ycombinator.com",
  "render_js": false,
  "output": ["json"],
  "extract": {
    "mode": "schema",
    "schema": {
      "top_stories": "array of the top 10 story titles and their point counts",
      "posting_date": "date of the front page"
    }
  }
}

Response:

{
  "outputs": {
    "json": {
      "top_stories": [
        { "title": "Example Story", "points": 342 }
      ],
      "posting_date": "2026-06-26"
    }
  }
}

`mode: "selectors"` — CSS selector extraction

Use CSS selectors when you know the DOM structure. This is deterministic and does not use an LLM.

{
  "url": "https://example.com/product",
  "output": ["json"],
  "extract": {
    "mode": "selectors",
    "fields": {
      "title": {
        "selector": "h1.product-title",
        "type": "text"
      },
      "price": {
        "selector": "span.price",
        "type": "text"
      },
      "image_url": {
        "selector": "img.product-image",
        "type": "attr",
        "attribute": "src"
      }
    }
  }
}

Field type options:

"text" — inner text content
"html" — inner HTML
"attr" — value of attribute

`mode: "instruction"` — free-form LLM instruction

Give the LLM an open-ended instruction when the schema isn’t predictable in advance. Same engine option as mode: "schema" applies here.

{
  "url": "https://example.com/article",
  "output": ["json"],
  "extract": {
    "mode": "instruction",
    "instruction": "Extract the author name, publication date, and a 2-sentence summary of this article."
  }
}

`mode: "page"` — raw page extraction

Returns the full page as a single field without any structuring. Useful when you want the LLM in your own application to do the structuring.

{
  "url": "https://example.com",
  "output": ["json"],
  "extract": { "mode": "page" }
}

Extraction errors

If extraction fails, the API returns status 422 with one of: schema_validation_failed (schema mode couldn’t resolve a requested field), instruction_limits_exceeded (instruction mode exceeded its field/token limits), llm_unavailable (LLM extraction requested but no provider configured or reachable), or selectors_unsupported (an unsupported selector or field type). See Error Reference for the full list. The failure detail is in error.message, and the response also includes a diagnostics object ({ outcome: "failed", retryable, blocked?, timed_out? }) describing whether the failure is worth retrying.

Cost

Any request with an extract config (any mode, including selectors) costs a flat 5 credits if extraction ran through the LLM, or 2 credits otherwise — it does not vary with page length or scale per-field.

Getting Started

Guides

API Reference

Extracting Structured Data

Extraction modes

`mode: "schema"` — described-field extraction

`mode: "selectors"` — CSS selector extraction

`mode: "instruction"` — free-form LLM instruction

`mode: "page"` — raw page extraction

Extraction errors

Cost

​Extraction modes

​mode: "schema" — described-field extraction

​mode: "selectors" — CSS selector extraction

​mode: "instruction" — free-form LLM instruction

​mode: "page" — raw page extraction

​Extraction errors

​Cost

Extraction modes

`mode: "schema"` — described-field extraction

`mode: "selectors"` — CSS selector extraction

`mode: "instruction"` — free-form LLM instruction

`mode: "page"` — raw page extraction

Extraction errors

Cost