# 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.

<table><thead><tr><th width="233.2222900390625">Action</th><th width="226.778076171875">Result</th><th width="121.4815673828125">Response</th><th>Cost</th></tr></thead><tbody><tr><td>Create parser</td><td>Generates initial version of the parser, under version <code>0</code>.</td><td><code>201 Created</code></td><td>30 000 API Credits</td></tr><tr><td><code>PATCH</code> with <code>rename_fields</code> or <code>remove_fields</code></td><td>Creates new version immediately.</td><td><code>200 OK</code></td><td>Free</td></tr><tr><td><code>PATCH</code> with <code>add_fields</code> or <code>modify_fields</code></td><td>Generates a new version asynchronously.</td><td><code>202 Accepted</code></td><td>30 000 API Credits</td></tr></tbody></table>

{% hint style="info" %}
**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.
{% endhint %}

#### 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.

```bash
# 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](/ai-parser/pricing-and-limits.md) 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.&#x20;

#### 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](/ai-parser/pricing-and-limits.md) for more information about costs and plan limitations.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.scraperapi.com/ai-parser/understanding-parsers-and-versions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.