AI extraction
Get the fields you describe in a JSON Schema from any page, without writing selectors
AI extraction
Describe the data you want as a JSON Schema and get it back as JSON that matches the schema, from any page. No CSS selectors to write or maintain when a site changes its markup.
AI extraction is included on every plan, with a monthly allowance (see Limits). Each AI output that returns data uses one extraction; a long page uses one per part (see Long pages).
Request
Add a JSON output with "mode": "ai" and a JSON Schema in schema:
curl -X POST 'https://api.allscreenshots.com/v1/screenshots' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"url": "https://example.com/products/wool-runner",
"outputs": [{
"type": "json",
"id": "product",
"mode": "ai",
"schema": {
"type": "object",
"properties": {
"name": { "type": "string" },
"price": {
"type": "object",
"properties": {
"amount": { "type": ["number", "null"] },
"currency": { "type": ["string", "null"], "description": "ISO 4217 code" }
},
"required": ["amount", "currency"]
},
"sizes": { "type": "array", "items": { "type": "string" } },
"inStock": { "type": ["boolean", "null"] }
},
"required": ["name", "price", "sizes", "inStock"]
},
"prompt": "The product in the main section, not recommended products"
}]
}'| Option | Type | Description |
|---|---|---|
mode | string | "ai" |
schema | object | A JSON Schema with "type": "object" at the top |
prompt | string | Optional instructions about what to extract (up to 2,000 characters) |
selector | string | Optional CSS selector: only the matching elements of the page are read (up to 1,000 characters). Useful on long pages: e.g. "main table" |
It works everywhere outputs work: sync and async requests, bulk requests and schedules. You can combine it with other outputs, such as a screenshot or Markdown of the same page load.
Response
data is an object that matches your schema. Values the page doesn't state are null, as long as your schema allows null for them:
{
"url": "https://example.com/products/wool-runner",
"outputs": {
"product": {
"type": "json",
"mode": "ai",
"contentType": "application/json",
"data": {
"name": "Wool Runner",
"price": { "amount": 98, "currency": "USD" },
"sizes": ["8", "9", "10", "11"],
"inStock": true
},
"size": 112
}
},
"renderTimeMs": 4100
}When nothing could be extracted, the request still succeeds: data is {}, the output has an error with a code and a message, and no extraction is used:
"product": {
"type": "json",
"mode": "ai",
"data": {},
"error": {
"code": "page_unavailable",
"message": "The site returned HTTP 405 instead of the page, so nothing was extracted. This does not count against your AI extraction allowance.",
"httpStatus": 405
}
}| Code | What happened | What to do |
|---|---|---|
page_unavailable | The site returned an error status (in httpStatus) or showed a bot check instead of its content | Check the URL; some sites don't serve automated browsers |
page_too_large | The page would take more than 16 extractions | Use selector to read only the part you need |
result_too_large | The result is longer than AI extraction can return | Ask for fewer fields, or use selector |
selector_not_found | Nothing on the page matches selector | Check the selector against the page |
invalid_selector | selector is not a valid CSS selector | Fix the selector |
content_not_processed | The page's content could not be processed | Use a JSON output with selectors |
extraction_failed | A temporary error | Retry the request |
allowance_exhausted | This month's AI extractions ran out, or a long page needs more than are left | Use selector, upgrade, or wait for the next billing period |
ai_unavailable | AI extraction is temporarily unavailable | Retry later |
Long pages
A long page is read in parts and the results are combined into one answer: lists are joined in page order, and single values come from the first part that has them. Each part uses one extraction, and the output says how many it used:
"items": {
"type": "json",
"mode": "ai",
"data": { "items": ["...", "..."] },
"extractions": 3
}Most pages are one part; very long pages, such as large tables, long product lists or a whole book on one page, take several. One output reads at most 16 parts; a longer page returns the page_too_large error. The whole page is always read: you get all of it or an error, never part of a result.
To read less of a long page (fewer extractions, faster), set selector to the part you need, such as "main table" or "#results". With a selector, the page's structured data (JSON-LD) is not included.
Writing a schema
- Describe each field with
descriptionwhen the name alone could be read two ways ("price": "current selling price of the default variant"). - Allow
null("type": ["string", "null"]) for anything a page may not have, so the result says so instead of guessing. - Use arrays of objects for lists (rows of a table, products in a listing, comments).
- Use
promptwhen a page has several candidates (a product page with recommendations, a page with several tables).
Supported keywords: type (including arrays of types such as ["string", "null"]), properties, required, items, enum, const, anyOf, format (date, date-time, time, duration, email, hostname, uri, ipv4, ipv6, uuid) and description. title, examples, default and $schema are accepted and ignored. Objects never get properties outside their schema. A schema can be up to 16 KB, 8 levels deep and 200 properties.
Speed
An AI output adds a few seconds to a request. It doesn't hold up the other outputs of the same request.
Limits
| Plan | AI extractions per month |
|---|---|
| Free | 100 |
| Starter | 500 |
| Pro | 600 |
| Business | 4,000 |
| Scale | 10,000 |
| Enterprise | Unlimited |
Each AI output that returns data uses one extraction per part of the page (most pages are one part); a request with two AI outputs on a normal page uses two. The request itself also counts as one screenshot. Check your usage with GET /v1/usage under quota.aiExtraction (monthlyLimit, used, remaining; limit and remaining are null on unlimited plans). It is also shown in the dashboard when you pick the AI mode of a JSON output.
Errors
| Status | Error | Description |
|---|---|---|
400 | VALIDATION_ERROR | The schema or prompt is invalid. The message names the problem, e.g. outputs: schema.properties.price.minLength is not supported |
402 | AI_EXTRACTION_QUOTA_EXCEEDED | This month's AI extractions are used up. Upgrade, or use a JSON output with selectors or without a schema |
503 | AI_EXTRACTION_UNAVAILABLE | AI extraction is temporarily unavailable. Retry later, or use a JSON output with selectors |
Data processing
With an AI output, the page's content (its text, links and structured data) together with your schema and prompt is sent to our AI provider, Anthropic. Nothing is sent for requests without AI outputs.