Understanding Parsers & Versions

There are two concepts to internalize before using the AI Parser API: parsers and versions.

What's a parser?

A parser is the AI model trained on your example URLs. It learns the structure of a specific page template (for example, product pages on quotes.toscrape.com) and applies that understanding to any similar URL you route through it.

Each parser has:

• A unique ID (e.g. 231fc251-decf-45ee-b7d8-738ac4a8hj76) returned when you create it.

• A name you give it for your own reference.

• A status - GENERATING during creation, FINISHED once ready and FAILED if something went wrong.

• One or more versions (more on that below).

What's a version?

A version is a snapshot of your parser's schema at a given point in time. The first version created is 0. Every time you change the parser's fields with PATCH, a new version is created.

Action	Result	Response	Cost
Create parser	Generates initial version of the parser, under version 0.	201 Created	30 000 API Credits
PATCH with rename_fields or remove_fields	Creates new version immediately.	200 OK	Free
PATCH with add_fields or modify_fields	Generates a new version asynchronously.	202 Accepted	30 000 API Credits

The reason for the split: when adding or modifying fields, the system has to re-analyze the pages, which takes time. Renaming or removing existing fields is just a schema edit and is applied instantly.

Specifying a version when parsing

When you call GET /parse/{parser_id}/{version}, the version is optional:

• Omit it → the latest version is used. Recommended for development.

• Specify it → you pin to that exact version. Recommended for production, so changes you make while iterating don't break your live extraction.

# Always uses latest
GET https://aiparser.scraperapi.com/parse/231fc251-decf-45ee-b7d8-738ac4a8hj76?api_key=API_KEY&url=URL

# Pinned to version 2
GET https://aiparser.scraperapi.com/parse/231fc251-decf-45ee-b7d8-738ac4a8hj76/2?api_key=API_KEY&url=URL

The Free parser

Every plan (including the Free plan) comes with one free parser. The first parser you create costs nothing. With it, you can parse URLs freely (standard scraping cost still applies) and rename or remove fields at no cost. Adding or modifying fields requires a paid plan, since those operations trigger generation. See Pricing & Limits for costs and plan limits information.

Editing vs Creating

Creating and updating a parser both cost 30 000 API Credits. Choose based on what you need:

• Create a new parser when the site's layout has changed significantly or you want to parse a different type of page altogether (product URL type → Search URL type).

• Update an existing parser when you want to change the extracted fields from the same page template. This keeps the same parser ID and adds to its verrsion history.

Credits & versioning

Each parser generation (creating a parser or adding/modifying fields via PATCH) consumes API credits. Renaming and removing fields is free, since these operations don't trigger generation. See Pricing & Credits for more information about costs and plan limitations.