Allscreenshots
Features

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"
    }]
  }'
OptionTypeDescription
modestring"ai"
schemaobjectA JSON Schema with "type": "object" at the top
promptstringOptional instructions about what to extract (up to 2,000 characters)
selectorstringOptional 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
  }
}
CodeWhat happenedWhat to do
page_unavailableThe site returned an error status (in httpStatus) or showed a bot check instead of its contentCheck the URL; some sites don't serve automated browsers
page_too_largeThe page would take more than 16 extractionsUse selector to read only the part you need
result_too_largeThe result is longer than AI extraction can returnAsk for fewer fields, or use selector
selector_not_foundNothing on the page matches selectorCheck the selector against the page
invalid_selectorselector is not a valid CSS selectorFix the selector
content_not_processedThe page's content could not be processedUse a JSON output with selectors
extraction_failedA temporary errorRetry the request
allowance_exhaustedThis month's AI extractions ran out, or a long page needs more than are leftUse selector, upgrade, or wait for the next billing period
ai_unavailableAI extraction is temporarily unavailableRetry 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 description when 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 prompt when 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

PlanAI extractions per month
Free100
Starter500
Pro600
Business4,000
Scale10,000
EnterpriseUnlimited

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

StatusErrorDescription
400VALIDATION_ERRORThe schema or prompt is invalid. The message names the problem, e.g. outputs: schema.properties.price.minLength is not supported
402AI_EXTRACTION_QUOTA_EXCEEDEDThis month's AI extractions are used up. Upgrade, or use a JSON output with selectors or without a schema
503AI_EXTRACTION_UNAVAILABLEAI 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.

On this page