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
urlandhtml. 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 ofschemaandprompt. 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 | alwaysdefaultauto- 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_msintegerdefault30000- 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"]
}
}'type Book = { title: string; price: number; in_stock: boolean };
const res = await fetch("https://api.siftzo.com/v1/extract", {
method: "POST",
headers: {
"X-API-Key": process.env.SIFTZO_API_KEY!,
"Content-Type": "application/json",
},
body: JSON.stringify({
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"],
},
}),
signal: AbortSignal.timeout(120_000),
});
const result = await res.json();
if (!res.ok) throw new Error(result.error.code);
const book = result.data as Book;
console.log(book.title, book.price, result.credits);import os
import requests
res = requests.post(
"https://api.siftzo.com/v1/extract",
headers={"X-API-Key": os.environ["SIFTZO_API_KEY"]},
json={
"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"],
},
},
timeout=120,
)
result = res.json()
res.raise_for_status()
print(result["data"], result["credits_detail"])package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"os"
"time"
)
func main() {
payload, _ := json.Marshal(map[string]any{
"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": map[string]any{
"type": "object",
"properties": map[string]any{
"title": map[string]string{"type": "string"},
"price": map[string]string{"type": "number"},
"in_stock": map[string]string{"type": "boolean"},
},
"required": []string{"title", "price", "in_stock"},
},
})
req, _ := http.NewRequest("POST", "https://api.siftzo.com/v1/extract", bytes.NewReader(payload))
req.Header.Set("X-API-Key", os.Getenv("SIFTZO_API_KEY"))
req.Header.Set("Content-Type", "application/json")
client := &http.Client{Timeout: 120 * time.Second}
res, err := client.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
var result struct {
Status string `json:"status"`
Credits int `json:"credits"`
Data struct {
Title string `json:"title"`
Price float64 `json:"price"`
InStock bool `json:"in_stock"`
} `json:"data"`
}
json.NewDecoder(res.Body).Decode(&result)
fmt.Println(res.StatusCode, result.Data.Title, result.Data.Price, result.Credits)
}Response
{
"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.
nullforhtmlinput. dataany | null- The extracted JSON. With a schema it always validates against it.
nullwhen the request failed. modelstring- The model that produced the data.
usageobjectinput_tokensandoutput_tokensacross 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
htmlinput,tierisnullandattemptsis 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
statusisfailed:codeandmessage.
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.additionalPropertiesmay only befalse. - Any other keyword, such as
$ref,oneOforpatternProperties, is refused with400 invalid_request. - Use
descriptionon 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.
| HTTP | Code | Billed | When |
|---|---|---|---|
| 400 | invalid_request | No | Both or neither of url and html, no schema and no prompt, or a schema that breaks the rules below. |
| 402 | credits_exhausted | Scrape only, if fetched | Your monthly credits are used up, or what is left cannot cover one model call for the page. |
| 402 | llm_tokens_exhausted | No | The account's monthly LLM token cap is reached. |
| 403 | target_not_allowed | No | A private address or a blocked domain. |
| 408 | timeout | No | The scrape or the model ran out of time. |
| 424 | target_blocked, target_unreachable, proxy_unavailable, response_too_large | No | The page could not be fetched, as for a scrape. |
| 424 | extraction_failed | Scrape only | The model's answer was not valid JSON for the schema, also after one repair, or the model declined. |
| 429 | concurrency_limit | No | Too many requests running. |
| 503 | extraction_unavailable | No | AI extraction is not available right now. |
| 503 | overloaded | No | No 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
htmlinput. - 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_exhausteduntil 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.