Reference

AI extraction

Describe the data you want with a JSON Schema, a prompt or both. Siftzo fetches the page, has a language model read it and returns JSON that matches your schema.

POST /v1/extract

The body is a JSON object; unknown fields are rejected with 400 invalid_request. Extraction is synchronous only: the call returns when the data is ready. Authentication and concurrency work as for POST /v1/scrape.

urlstring
The page to scrape and extract from. Exactly one of url and html. The same rules as for POST /v1/scrape.
htmlstring
Raw HTML you already have. Nothing is fetched and no scrape credits are charged. The whole request body can be at most 2 MB.
schemaobject
A JSON Schema the result must match, with type: "object" at the root. See schema rules. At least one of schema and prompt.
promptstring
1–4,000 characters of instructions: what to extract, units, how to treat missing values. Without a schema, the model returns any JSON value it finds fitting.
renderauto | never | alwaysdefault auto
How the page is fetched, as for a scrape. See Rendering. Only with url.
countrystring
Exit country as an ISO 3166-1 alpha-2 code. Only with url.
wait_forstring
A CSS selector to wait for before reading the page. Forces the browser tier. Only with url.
timeout_msintegerdefault 30000
5,000–50,000. The deadline for the scrape. The model has its own budget of 50 seconds.
curl https://api.siftzo.com/v1/extract \
  -H "X-API-Key: $SIFTZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",
    "prompt": "The book on this page. Price as a number without currency.",
    "schema": {
      "type": "object",
      "properties": {
        "title": { "type": "string" },
        "price": { "type": "number" },
        "in_stock": { "type": "boolean" }
      },
      "required": ["title", "price", "in_stock"]
    }
  }'

Response

200 OK
{
  "id": "01K74E8R2M5W1QH7ZT3XJ9BCNA",
  "status": "done",
  "url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",
  "final_url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",
  "status_code": 200,
  "data": {
    "title": "A Light in the Attic",
    "price": 51.77,
    "in_stock": true
  },
  "model": "claude-sonnet-5-5",
  "usage": { "input_tokens": 8123, "output_tokens": 912 },
  "repaired": false,
  "content_truncated": false,
  "tier": "http",
  "attempts": 1,
  "credits": 103,
  "credits_detail": { "scrape": 1, "llm": 102 },
  "duration_ms": 9120
}
idstring
Request ID, the same as the X-Request-Id header.
statusdone | failed
Whether you got data.
url, final_url, status_code
The page as fetched, after redirects. null for html input.
dataany | null
The extracted JSON. With a schema it always validates against it. null when the request failed.
modelstring
The model that produced the data.
usageobject
input_tokens and output_tokens across all model calls, including a repair. Output tokens include the model's reasoning.
repairedboolean
true when the first answer did not match the schema and a second call fixed it.
content_truncatedboolean
true when the page was longer than the model's input limit and was cut. Data from the end of a very long page may be missing.
tier, attempts
As for a scrape. For html input, tier is null and attempts is 0.
creditsinteger
Credits charged, with the split in credits_detail (scrape, llm). See credits.
duration_msinteger
Time spent inside Siftzo, in milliseconds.
errorobject
Only when status is failed: code and message.

Schema rules

The schema is a subset of JSON Schema that every model can follow reliably. The root must be "type": "object", and every object must list its properties.

  • At most 16 KB serialised, 5 levels of nesting and 100 properties in total.
  • Allowed keywords: type, properties, required, items, enum, const, description, title, anyOf, format, minimum, maximum, exclusiveMinimum, exclusiveMaximum, minLength, maxLength, pattern, minItems, maxItems, additionalProperties. additionalProperties may only be false.
  • Any other keyword, such as $ref, oneOf or patternProperties, is refused with 400 invalid_request.
  • Use description on a property to tell the model what you mean, for example "Price including VAT, as a number".

With only a prompt, the model chooses the shape. That is handy for exploring a page, but use a schema in production so every answer has the same fields.

Errors

Errors before anything runs return only an error object. Failures after the page was fetched return the result object above with status: "failed", data: null and an error. See Errors.

Errors from POST /v1/extract
HTTPCodeBilledWhen
400invalid_requestNoBoth or neither of url and html, no schema and no prompt, or a schema that breaks the rules below.
402credits_exhaustedScrape only, if fetchedYour monthly credits are used up, or what is left cannot cover one model call for the page.
402llm_tokens_exhaustedNoThe account's monthly LLM token cap is reached.
403target_not_allowedNoA private address or a blocked domain.
408timeoutNoThe scrape or the model ran out of time.
424target_blocked, target_unreachable, proxy_unavailable, response_too_largeNoThe page could not be fetched, as for a scrape.
424extraction_failedScrape onlyThe model's answer was not valid JSON for the schema, also after one repair, or the model declined.
429concurrency_limitNoToo many requests running.
503extraction_unavailableNoAI extraction is not available right now.
503overloadedNoNo capacity. Retry shortly.

Credits

An extraction costs the scrape plus the model's tokens:

  • Scrape: 1 credit on the HTTP tier, 10 on the browser tier, 0 for html input.
  • Model: ⌈(input tokens × 2 + output tokens × 10) / 300⌉ credits with the default model. Both counts are in usage.

Example: a page fetched over HTTP, read with 8,000 input tokens and answered with 1,000 output tokens, costs 1 + ⌈(8,000 × 2 + 1,000 × 10) / 300⌉ = 1 + ⌈26,000 / 300⌉ = 1 + 87 = 88 credits.

The formula follows the model provider's list price per token. Tokens from a repair call count towards the same totals. When the model fails (extraction_failed), only the scrape is billed.

Before the model runs, Siftzo sets aside the most its calls can cost for that page: two calls with the maximum output, so a repair is possible. When the remaining credits only cover one call, the request runs with one call and no repair. When they do not cover even one, the answer is 402 credits_exhausted, and the scrape is still billed if the page was already fetched. After the model has answered, the reservation is replaced by the price of the tokens actually used.

Limits

  • At most 30,000 input tokens per model call. Longer pages are cut (content_truncated).
  • At most 4,096 output tokens per call, and at most 2 calls (one repair) per request.
  • A monthly LLM token cap per account, by default 5,000,000 tokens. Past it, requests get 402 llm_tokens_exhausted until the next month (UTC).
  • Prompt up to 4,000 characters. Request body up to 2 MB.
  • Extraction counts towards your concurrency limit like any other request.

Language models can misread a page. Check values that matter, such as prices, before you act on them. For product and article pages, the Data API reads structured data first and is cheaper.