Use the structured format when downstream code needs validated JSON rather than a free-form page representation. CrawlVolt evaluates the schema against the final rendered HTML, after browser actions when called through /v1/browse.

Structured extraction is deterministic. It does not send page content to an LLM and does not guess fields that are absent from the document.

Custom schema

Each field has a CSS selector. The default source is visible text and the default type is string.

curl --request POST https://www.crawlvolt.com/v1/scrape \
  --header "Authorization: Bearer $CRAWLVOLT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://store.example/products/tea",
    "formats": ["structured", "markdown"],
    "extract": {
      "fields": {
        "name": {
          "selector": "main h1",
          "required": true
        },
        "price": {
          "selector": "[itemprop=price]",
          "type": "number",
          "required": true
        },
        "in_stock": {
          "selector": "[data-available]",
          "source": "attribute",
          "attribute": "data-available",
          "type": "boolean"
        },
        "images": {
          "selector": "main img[src]",
          "source": "attribute",
          "attribute": "src",
          "type": "url",
          "multiple": true
        }
      }
    }
  }'

Supported sources are text, html and attribute. Supported scalar types are string, number, boolean and url. Relative URLs are resolved against the final page URL. A schema can contain at most 64 fields and every selector is validated before browser work is billed. CrawlVolt caps each field at 1,000 matches and 256 KiB per value, with a 4 MiB structured source-value budget per request. The normal max_output_bytes response cap still applies after extraction.

Result contract

The result is returned in outputs.structured:

{
  "valid": true,
  "confidence": 1.0,
  "data": {
    "name": "Green tea",
    "price": 12.5,
    "in_stock": true,
    "images": ["https://store.example/images/tea.jpg"]
  },
  "fields": {
    "name": { "matched_count": 1, "confidence": 1.0 },
    "price": { "matched_count": 1, "confidence": 1.0 }
  },
  "errors": []
}

valid is false when a required field is missing or a matched value cannot be converted to its declared type. errors identifies the field and returns required_missing or type_conversion_failed. confidence is the fraction of schema fields that produced correctly typed values; optional fields that are absent lower confidence without making the result invalid.

Presets

Presets provide conservative defaults and can be extended or overridden by custom fields.

Article

{
  "url": "https://example.com/news/launch",
  "formats": ["structured"],
  "extract": { "preset": "article" }
}

Returns title, author, published_at and body.

Product

{
  "url": "https://store.example/products/42",
  "formats": ["structured"],
  "extract": { "preset": "product" }
}

Returns name, price, currency, description and availability from common semantic attributes and page markup.

Documentation

{
  "url": "https://example.com/docs/quickstart",
  "formats": ["structured", "markdown"],
  "extract": { "preset": "documentation" }
}

Returns title, content, sections and code_samples while preserving the raw Markdown output requested alongside it.

After browser actions

The same extract object works with POST /v1/browse. CrawlVolt runs the action sequence first, then evaluates the schema against the resulting DOM. This is useful for tabs, consent dialogs and authenticated session content.

Structured extraction