POST /v1/extract

Extract structured data from a URL or HTML string.

Without a schema, runs the free JSON-LD cascade (JSON-LD → Open Graph → regex). No LLM cost. Every field carries _confidence and _provenance.

With a schema, uses an LLM to extract data matching your exact JSON structure. The model is chosen automatically based on your plan tier and the complexity flag.

You can pass a url (the API fetches it for you), a urls array for many pages at once, raw html, or pre-converted markdown.

Multi-URL mode

Pass urls: string[] (max 100) to extract from many pages in one call. The response is { results: [{ url, ok, data?, error? }], summary: { total, ok, failed } } instead of a single object. Invalid URLs are rejected up front with a 400 listing them in invalidUrls.

Request

POST /v1/extract
Content-Type: application/json
x-api-key: YOUR_KEY

Body

Field	Type	Required	Default	Description
`url`	string	Conditional		URL to fetch and extract. Required if `html`/`urls` is not provided.
`urls`	string[]	Conditional		Extract from many URLs in one call (max 100, concurrency 5). Returns `{ results[], summary }` instead of a single object.
`html`	string	Conditional		Raw HTML to extract from. Skips the fetch step. Required if `url` is not provided.
`markdown`	string	No		Pre-converted markdown. If omitted alongside `html`, the engine converts HTML automatically.
`schema`	object	No		JSON schema describing the structure to extract. When omitted, free JSON-LD cascade runs.
`complexity`	`"low"` \| `"high"`	No	`"low"`	Extraction complexity. `"high"` routes to a smarter model.

Example, schema-free (JSON-LD cascade)

curl -X POST https://api.superscraper.dev/v1/extract \
  -H "x-api-key: ss_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.angi.com/companylist/us/tx/austin/plumbers.htm"}'

Example, schema extraction

curl -X POST https://api.superscraper.dev/v1/extract \
  -H "x-api-key: ss_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.buildzoom.com/contractor/apex-roofing-llc",
    "schema": {
      "type": "object",
      "properties": {
        "company_name": { "type": "string" },
        "license_number": { "type": "string" },
        "license_state": { "type": "string" },
        "years_in_business": { "type": "number" },
        "specialties": {
          "type": "array",
          "items": { "type": "string" }
        },
        "bbb_rating": { "type": "string" }
      }
    },
    "complexity": "low"
  }'

Response

Schema-free response

Returns the listing extraction result directly:

{
  "url": "https://www.angi.com/companylist/us/tx/austin/plumbers.htm",
  "data": {
    "name": "Austin Plumbing Pros",
    "phone": "(512) 555-0134",
    "address": "3210 E Cesar Chavez St",
    "city": "Austin",
    "state": "TX",
    "zip": "78702",
    "rating": 4.6,
    "review_count": 189,
    "_confidence": 0.87,
    "_extraction_method": "json-ld"
  }
}

Schema extraction response

{
  "url": "https://www.buildzoom.com/contractor/apex-roofing-llc",
  "data": {
    "company_name": "Apex Roofing LLC",
    "license_number": "TX-RFG-204817",
    "license_state": "TX",
    "years_in_business": 12,
    "specialties": ["Asphalt shingles", "Metal roofing", "Storm damage"],
    "bbb_rating": "A+"
  },
  "schema": {
    "type": "object",
    "properties": {
      "company_name": { "type": "string" },
      "license_number": { "type": "string" },
      "license_state": { "type": "string" },
      "years_in_business": { "type": "number" },
      "specialties": { "type": "array", "items": { "type": "string" } },
      "bbb_rating": { "type": "string" }
    }
  },
  "metadata": {
    "model": "deepseek-coder",
    "costUsd": 0.000031,
    "latencyMs": 1840
  }
}

Model routing

The LLM model is selected automatically. schema extraction routes are the only calls that incur LLM cost.

Condition	Model	Cost (per 1M tokens in/out)
Free tier (any)	`llama-3.3` via Groq	Free
Paid tier + `complexity: "low"`	`deepseek-coder`	$0.14 / $0.28
Paid tier + `complexity: "high"`	`claude-haiku`	$0.80 / $4.00
Free-form / unstructured content	`claude-sonnet`	$3.00 / $15.00

Schema-free extraction (no schema field) always runs the deterministic JSON-LD cascade, zero LLM cost regardless of tier.

Cost per extraction

Typical extraction costs at ~2 000 input tokens + ~500 output tokens:

Model	Typical cost
`llama-3.3` (free tier)	$0.000000
`deepseek-coder` (low complexity)	$0.000028
`claude-haiku` (high complexity)	$0.000320
`claude-sonnet` (unstructured)	$0.001350

Scrape Search