> For the complete documentation index, see [llms.txt](https://docs.scraperapi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scraperapi.com/integrations/automation-and-workflow-integrations/n8n-integration/ai-parser-less-than-greater-than-n8n.md).

# AI Parser <--> n8n

The `AI Parser` turns raw HTML into clean, structured JSON. It needs 1-3 example URLs from the **same domain** that share the **same page layout** (3 product pages, 3 search pages, etc.) to generate a **reusable** parser tailored to that layout. The parser can then be used with any similar page on the **same site** to extract the **same fields** automatically.

#### How it Works

1. **Create a Parser** - provide a name and up to 3 example URLs of the same page type. Generation is asynchronous. The node returns an **`id`** and a **`version`**.&#x20;
2. **Wait for generation** - use the `Get a Parser` operation to check status (`GENERATING`, `FINISHED` or `FAILED`). Wait until `FINISHED` before parsing.
3. **Run the Parser** - use the `Parse a URL` operation to extract structured JSON from any URL with the same page layout.

#### Using the AI Parser in a workflow

1. Add a ScraperAPI Node .
2. Select **Create a Parser**, enter a **Name** and give up to 3 Example URLs, then execute.
3. Copy the returned `parser id`.
4. Add another node, select **Get a Parser**, enter the `parser id` and execute until the status is `FINISHED`.
5. Add another node, select **Parse a URL,** enter the `parser id` and a target URL.
6. Execute to get structured JSON for your downstream nodes.

{% hint style="success" %}
**Tip**: Provide CSS or XPATH selectors for the exact fields that you expect to get back in the praser. This guides generation and keeps the output shape predictable, instead of relying on the AI to infer which fields matter.
{% endhint %}

#### Actions

The ScraperAPI node exposes six AI Parser actions:

<mark style="background-color:blue;">**▸ Create a Parser**</mark> \
Builds a new parser from 1-3 example URLs. Generation is asynchronous. Poll Get a parser until the status is `FINISHED`.

<figure><img src="/files/T8eiEo1EazjU9ePYcDP5" alt=""><figcaption></figcaption></figure>

<details>

<summary>Example Response</summary>

```json
[
  {
    "resource": "aiparser",
    "response": {
      "body": {
        "id": "1786e41f-83f3-4487-9dc9-79ef84561e34",
        "version": 0
      },
      "statusCode": 201,
      "statusMessage": "Created"
    }
  }
]
```

</details>

<table><thead><tr><th width="228.7406005859375">Parameter</th><th width="134.0369873046875" align="center">Parameter Type</th><th>Description</th></tr></thead><tbody><tr><td><code>Name</code></td><td align="center">REQUIRED</td><td>A name to identify the parser.</td></tr><tr><td><code>Example URLs</code></td><td align="center">REQUIRED</td><td>1-3 example URLs of the same type.</td></tr><tr><td><code>Fields</code></td><td align="center">OPTIONAL</td><td>Predefined fields to guide generation. Each supports <strong>name</strong>, <strong>description</strong>, <strong>type</strong> (<code>string</code>, <code>number</code>, <code>array</code>), and an optional CSS or XPath <strong>selector</strong>. Use dot notation for nested fields (e.g. "<code>products.name</code>").</td></tr><tr><td><code>Scraper Parameters</code></td><td align="center">OPTIONAL</td><td>ScraperAPI parameters to be used when fetching the example pages - see <a href="https://docs.scraperapi.com/ai-parser/endpoints/create-a-parser#supported-scraperapi-parameters">supported parameters</a>.</td></tr></tbody></table>

<mark style="background-color:blue;">**▸ Get a Parser**</mark>\
Retrieves a parser's **status**, **fields** and **example results**. Use it to confirm generation has finished before parsing.

<figure><img src="/files/UGzsr6kdWozfeTXtiQ3a" alt=""><figcaption></figcaption></figure>

<details>

<summary>Example Response - <code>GENERATING</code></summary>

```json
{
  "name": "Bol_Product_Details",
  "created_at": "2026-07-23T10:16:34.099Z",
  "generated_at": null,
  "status": "GENERATING",
  "error": null,
  "example_result": null,
  "fields": [],
  "version": 0
}
```

</details>

<details>

<summary>Example Response - <code>FINISHED</code></summary>

```json
[
  {
    "resource": "aiparser",
    "response": {
      "body": {
        "name": "Bol_Product_Details",
        "created_at": "2026-07-23T10:16:34.099Z",
        "generated_at": "2026-07-23T10:22:03.682Z",
        "status": "FINISHED",
        "error": null,
        "example_result": [
          {
            "url": "https://www.bol.com/nl/nl/p/smartgames-dropzone-knikkerbaan/9300000176308949/",
            "result": {
              "product": [
                {
                  "brand": "SmartGames",
                  "price": 2199,
                  "title": "SmartGames Dropzone - Logisch Denkspel & Knikkerbaan - 80 Educatieve Bouwuitdagingen - Solospel - Vanaf 8 Jaar",
                  "images": [
                    {
                      "url": null
                    },
                    {
                      "url": null
                    },
                    {
                      "url": null
                    },
                    {
                      "url": null
                    },
                    {
                      "url": null
                    },
                    {
                      "url": null
                    }
                  ],
                  "avg_rating": 49,
                  "description": "SmartGames Dropzone: hét revolutionaire knikkerbaan-puzzelspel! Leid de knikkers naar de finish in 80 opdrachten. Gebruik creatieve bouwtechnieken om een dynamische knikkerbaan te ontwerpen en leid de knikkers feilloos naar hun juiste eindbestemming. Zet je schrap voor spanning, actie en een flinke dosis zwaartekracht! Met SmartGames Dropzone haal je het ultieme knikkerbaan-puzzelspel in huis. Het doel is even eenvoudig als uitdagend: bouw een functionerend parcours met verschillende paden en zorg dat elke knikker in de juiste doelbasis rolt. Maar pas op, dit spel heeft een unieke, revolutionaire twist: in tegenstelling tot andere SmartGames tonen de opdrachten in het boekje niet de startopstelling, maar juist de eindpositie van de knikkers! Je moet dus achterwaarts leren denken en deductie gebruiken om te achterhalen hoe de baanstukken geplaatst moeten worden om dat exacte resultaat te bereiken. Eindeloos experimenteren met zwaartekracht en logica SmartGames Dropzone is een hoogwaardig solospel dat perfect geschikt is voor kinderen vanaf 8 jaar én volwassenen die van een mechanische uitdaging houden. Het spel is gemaakt van stevig kunststof en metaal, waardoor het bestand is tegen urenlang bouwen, testen en experimenteren. Met maar liefst 80 unieke uitdagingen raak je nooit uitgespeeld. Elke opdracht dwingt je om opnieuw te kijken naar richting, snelheid en zwaartekracht. Het is de ideale manier om op een natuurlijke wijze essentiële cognitieve vaardigheden te stimuleren, zoals het ruimtelijk inzicht, de planning, logisch redeneren en het probleemoplossend denken. Hoe speel je het?   Bestudeer het doel: Open het opdrachtenboekje en kies een uitdaging. Kijk goed naar de aangegeven eindposities van de knikkers onderaan de baan.   Bouw de knikkerbaan: Gebruik je logica en creativiteit om de baanstukken zo op het verticale bord te plaatsen dat de knikkers via de juiste splitsingen en paden naar beneden zullen rollen.   Test de dropzone: Laat de knikkers los vanaf de top! Komen alle ballen exact in de juiste opvangbakjes terecht? Dan heb je de code gekraakt.   Wat zit er in de doos?   1x Stevig verticaal basisbord van hoogwaardig kunststof en metaal   Diverse magnetische of klikbare knikkerbaanstukken   Set met metalen knikkers   1x Boekje met 80 opdrachten en oplossingen, oplopend in moeilijkheidsgraad   Over SmartGames: Al spelend de wereld ontdekken Welkom bij SmartGames, de wereldwijde expert in logische denkspeeltjes! Vanuit ons hoofdkantoor in Kontich (België) ontwerpt ons interne designteam al decennialang bekroond en kwalitatief educatief speelgoed. Elk spel is ontworpen om de cognitieve en sociale vaardigheden van spelers te prikkelen en te versterken. Onze missie is simpel: leren moet leuk zijn, voor iedereen! Of je nu aan de slag gaat met de meeslepende logica van SmartGames®, het magnetische peuterspeelgoed van SmartMax®, de stoere constructies van GeoSmart®, of de creatieve DIY sets van Smartivity®, je kiest gegarandeerd voor duurzaamheid, topkwaliteit en urenlang speelplezier.",
                  "specifications": "Verpakkingsgewicht0.47 kg"
                }
              ]
            }
          },
          {
            "url": "https://www.bol.com/nl/nl/p/ravensburger-legpuzzel-all-seasons-flowershop-1000-stukjes/9300000199135450/",
            "result": {
              "product": [
                {
                  "brand": "Ravensburger",
                  "price": 2295,
                  "title": "Ravensburger Legpuzzel - All Seasons Flowershop - 1000 Stukjes",
                  "images": [
                    {
                      "url": null
                    },
                    {
                      "url": null
                    },
                    {
                      "url": null
                    }
                  ],
                  "avg_rating": 50,
                  "description": "Ravensburger Legpuzzel - All Seasons Flowershop - 1000 Stukjes Beschrijving:Stap binnen in de kleurrijke wereld van de All Seasons Flowershop met deze Ravensburger legpuzzel van 1000 stukjes. Geniet van een gedetailleerde en levendige afbeelding van een bloemenwinkel die elk seizoen tot leven brengt met een scala aan prachtige bloemen en decoraties. De hoogwaardige puzzelstukken, voorzien van Ravensburger's unieke Softclick-technologie, zorgen voor een perfecte pasvorm en een moeiteloze puzzelervaring. Gemaakt van duurzaam materiaal, is deze puzzel ideaal voor liefhebbers van bloemen en gedetailleerde scènes. Kenmerken:  Puzzel van 1000 stukjes met een bloemenwinkelthema. Levendige en gedetailleerde illustratie. Perfecte pasvorm dankzij Softclick-technologie. Gemaakt van duurzame en hoogwaardige materialen.  Beleef urenlang puzzelplezier met Ravensburger en laat je inspireren door de schoonheid van bloemen in elk seizoen!",
                  "specifications": "Aanbevolen minimum leeftijd14 jaarGeslachtVolwassenen"
                }
              ]
            }
          },
          {
            "url": "https://www.bol.com/nl/nl/p/ravensburger-merry-mushroom-village-puzzel-1000-stukjes/9300000199135447/",
            "result": {
              "product": [
                {
                  "brand": "Ravensburger",
                  "price": 1399,
                  "title": "Ravensburger - Merry Mushroom Village - Puzzel - 1000 Stukjes",
                  "images": [
                    {
                      "url": null
                    },
                    {
                      "url": null
                    },
                    {
                      "url": null
                    },
                    {
                      "url": null
                    },
                    {
                      "url": null
                    },
                    {
                      "url": null
                    },
                    {
                      "url": null
                    }
                  ],
                  "avg_rating": 50,
                  "description": "Ravensburger - Merry Mushroom Village - Puzzel - 1000 Stukjes Stap in de magische wereld van de Merry Mushroom Village met deze prachtige 1000-stukjes Ravensburger puzzel. Deze puzzel biedt urenlang plezier voor zowel beginnende als ervaren puzzelaars. De gedetailleerde afbeelding brengt het betoverende dorp tot leven, en dankzij de hoogwaardige kwaliteit van Ravensburger puzzels past elk stukje naadloos in het andere.  Thema: Merry Mushroom Village Stukjes: 1000 Aanbevolen Leeftijd: Voor volwassenen en ervaren puzzelaars Afmetingen (voltooid): 70 x 50 cm  Kenmerken:  Hoogwaardige kwaliteit: Ravensburger staat bekend om zijn uitzonderlijke kwaliteit, en dat is ook het geval voor deze puzzel. De stukjes zijn vervaardigd met met de hand gemaakte stansmessen, wat zorgt voor oneindige vormvariaties en een perfect passend resultaat. Voor jong en oud: De puzzel is geschikt voor alle leeftijden, zodat zowel jonge als oudere puzzelaars van deze uitdaging kunnen genieten. Kunstwerk om in te lijsten: Het resultaat van deze puzzel is een prachtig kunstwerk dat je kunt inlijsten en ophangen om van te genieten.  Geniet van het puzzelen met Ravensburger en laat je onderdompelen in het charmante Merry Mushroom Village!",
                  "specifications": "Aanbevolen minimum leeftijd14 jaarGeslachtVolwassenen"
                }
              ]
            }
          }
        ],
        "fields": [
          {
            "name": "product",
            "type": "array"
          },
          {
            "name": "product.title",
            "type": "text"
          },
          {
            "name": "product.price",
            "type": "text"
          },
          {
            "name": "product.description",
            "type": "text"
          },
          {
            "name": "product.brand",
            "type": "text"
          },
          {
            "name": "product.avg_rating",
            "type": "text"
          },
          {
            "name": "product.specifications",
            "type": "text"
          },
          {
            "name": "product.images",
            "type": "array"
          },
          {
            "name": "product.images.url",
            "type": "attribute"
          }
        ],
        "version": 0
      },
      "statusCode": 200,
      "statusMessage": "OK"
    }
  }
]
```

</details>

<details>

<summary>Example Response - <code>FAILED</code></summary>

```json
{
	"name": "Bol_Product_Details_Test",
	"created_at": "2026-07-23T10:36:14.099Z",
	"generated_at": "2026-07-23T10:36:17.162Z",
	"status": "FAILED",
	"error": "DownloadError: Failed to download https://www.bol.com/nl/nl/p/TestTest/TestTest/ after 3 retries",
	"example_result": null,
	"fields": [],
	"version": 0
}
```

</details>

<details>

<summary>Example Response - <code>NOT FOUND</code></summary>

```json
{
  "errorCode": 404,
  "fullMessage": "Request failed with status code 404",
  "errorData": {
    "error": "Parser not found"
  }
}
```

</details>

<table><thead><tr><th width="152.8516845703125">Parameter</th><th width="116.25927734375">Parameter Type</th><th>Description</th></tr></thead><tbody><tr><td><code>Parser ID</code></td><td>REQUIRED</td><td>The parser ID.</td></tr><tr><td><code>Version</code></td><td>OPTIONAL</td><td>A specific version to retrieve. Leave as <code>-1</code> for the latest.</td></tr></tbody></table>

<mark style="background-color:blue;">**▸ Update a Parser**</mark>\
Modifies fiels of an existing parser. Adding or modifying fields triggers the generation of a **new version**. renaming and removing are applied **immediately**.

<figure><img src="/files/MZAoPhtCZAZ6Vjndj7KA" alt=""><figcaption></figcaption></figure>

<details>

<summary>Example Response</summary>

```json
[
  {
    "resource": "aiparser",
    "response": {
      "body": {
        "id": "1786e41f-83f3-4487-9dc9-79ef84561e34",
        "version": 1
      },
      "statusCode": 200,
      "statusMessage": "OK"
    }
  }
]
```

</details>

<table><thead><tr><th width="152.8516845703125">Parameter</th><th width="115.5185546875">Parameter Type</th><th>Description</th></tr></thead><tbody><tr><td><code>Parser ID</code></td><td>REQUIRED</td><td>The parser ID.</td></tr><tr><td><code>Version</code></td><td>OPTIONAL</td><td>A specific version to update. Leave as <code>-1</code> for the latest.</td></tr><tr><td><code>Add Fields</code></td><td>OPTIONAL</td><td>Fields to add (<code>name</code>, <code>description</code>, <code>type</code>, <code>selector</code>).</td></tr><tr><td><code>Modify Fields</code></td><td>OPTIONAL</td><td>Modify existing field with clearer description if it was extracted incorrectly.</td></tr><tr><td><code>Rename Fields</code></td><td>OPTIONAL</td><td>Rename a filed (<code>name</code>, <code>new_name</code>).</td></tr><tr><td><code>Remove Fields</code></td><td>OPTIONAL</td><td>Remove fields from the parser. You can also drag and drop fields directly from the fields list.</td></tr></tbody></table>

<mark style="background-color:blue;">**▸ Parse a URL**</mark>\
Use an existing parser to extract data from a URL.

<figure><img src="/files/NjmVGADpGycSk27R10ed" alt=""><figcaption></figcaption></figure>

<details>

<summary>Example Response</summary>

```json
[
  {
    "resource": "aiparser",
    "response": {
      "body": {
        "parser": "1786e41f-83f3-4487-9dc9-79ef84561e34",
        "version": 1,
        "result": {
          "product": [
            {
              "title": "Princess Friteuse - 3 liter - Koude zone - Frituurpan - 2000W - Regelbare thermostaat - Zwart - 182727",
              "price": 3299,
              "description": "Beste Koop Consumentengids Augustus 2025 Met de Princess 3-liter Frituurpan ontdek je maximaal frituurgenot, perfect voor grotere porties met knapperige lekkernijen. Dankzij de grote inhoud van 3 liter kan je voor je hele gezin tegelijkertijd frietjes en snacks frituren. Daarnaast is de frietpan voorzien van een nauwkeurige regelbare thermostaat (tot 190 ºC) met oververhittingbeveiliging. Koude zone voor gezonder friturenEen probleem van veel friteuses is dat restjes in het hete vet terechtkomen en dan bij elk gebruik verbranden. De Princess Frituurpan Black heeft om dit te voorkomen een speciale koude zone. Alle kleine stukjes die door het mandje heen vallen komen in deze koude zone terecht en verbranden niet. Zo gaat je olie langer mee en krijg je geen ongezonde verbrande restjes op je gefrituurde producten. Makkelijk schoon te makenDe emaille binnenpan van de Princess Frituurpan is uitneembaar zodat je makkelijk de olie kan verversen en de binnenpan in de vaatwasser kan plaatsen. De gehele frietpan is eenvoudig uit elkaar te halen en de meeste onderdelen zijn vaatwasserbestendig dus het schoonmaken is gemakkelijk. Het handvat kan eenvoudig losgeklikt worden van het mandje zodat deze ook makkelijk gereinigd kan worden. Wat vind je in de doos:Princess Frituurpan Black, frituurmandje, uitneembare emaille binnenpan, handleiding Redenen om voor de Princess Frituurpan Black te kiezen: Bak genoeg frietjes voor je hele gezin dankzij de inhoud van 3 liter De koude zone voorkomt verbrande restjes en houdt de olie langer schoon Makkelijk schoon te maken dankzij de vaatwasserbestendige onderdelen Krachtig vermogen van 2000 Watt zodat de friteuse snel op temperatuur is",
              "brand": "Princess",
              "avg_rating": 44,
              "specifications": "Anti geurJaAutomatisch uitschakelenNeeKoude zone friteuseJaVerborgen verwarmingselementNeeGeïntegreerde oliefilterNeeMaximale temperatuur190 °CMinimale temperatuur80 °CTemperatuur indicatorJaTemperatuur instellingenJaTimerNeeVermogen2000 W"
            }
          ]
        }
      },
      "statusCode": 200,
      "statusMessage": "OK"
    }
  }
]
```

</details>

<table><thead><tr><th width="193.5924072265625">Parameter</th><th width="116.25927734375">Parameter Type</th><th>Description</th></tr></thead><tbody><tr><td><code>Parser ID</code></td><td>REQUIRED</td><td>The parser ID.</td></tr><tr><td><code>URL</code></td><td>REQUIRED</td><td>The target URL to scrape and parse.</td></tr><tr><td><code>Version</code></td><td>OPTIONAL</td><td>A specific version to apply. Leave as <code>-1</code> for the latest.</td></tr><tr><td><code>Scraper Parameters</code></td><td>OPTIONAL</td><td>ScraperAPI parameters to be used when fetching the target URL - see <a href="https://docs.scraperapi.com/ai-parser/endpoints/create-a-parser#supported-scraperapi-parameters">supported parameters</a>.</td></tr></tbody></table>

<mark style="background-color:blue;">**▸ List Parsers**</mark>\
Lists all parsers on your account. This one **does not** require any parameters.

<figure><img src="/files/1YWsWrpUvdTwio4rbW4O" alt=""><figcaption></figcaption></figure>

<details>

<summary>Example Response</summary>

```json
[
  {
    "resource": "aiparser",
    "response": {
      "body": [
        {
          "id": "13f4e80b-58d3-491e-aed1-3fb6cdc52eb9",
          "name": "TestParser",
          "status": "FINISHED",
          "error": null,
          "generated_at": "2026-07-23T11:01:40.223Z",
          "version": 0
        },
        {
          "id": "1786e41f-83f3-4487-9dc9-79ef84561e34",
          "name": "Bol_Product_Details",
          "status": "FINISHED",
          "error": null,
          "generated_at": "2026-07-23T11:07:19.629Z",
          "version": 1
        },
        {
          "id": "5baf4501-3506-4473-b949-fdc0328564c0",
          "name": "Amazon_Product_Price_Scraper",
          "status": "FAILED",
          "error": "Error: 400 This model's maximum context length is 200000 tokens. However, your messages resulted in 203623 tokens. Please reduce the length of the messages.",
          "generated_at": "2026-05-19T13:18:40.579Z",
          "version": 0
        },
        {
          "id": "3dbbbb35-3600-4f3e-82e8-e80a8eb95dce",
          "name": "Quotes Scraper",
          "status": "FINISHED",
          "error": null,
          "generated_at": "2026-05-18T13:41:05.214Z",
          "version": 0
        }
      ],
      "statusCode": 200,
      "statusMessage": "OK"
    }
  }
]
```

</details>

<mark style="background-color:blue;">**▸ Delete a Parser**</mark>\
**Permanently** delete a parser (and all its versions).

<figure><img src="/files/YtvxE4DYMCkWtq43GfUw" alt=""><figcaption></figcaption></figure>

<details>

<summary>Example Response</summary>

```json
[
  {
    "resource": "aiparser",
    "response": {
      "body": "",
      "statusCode": 204,
      "statusMessage": "No Content"
    }
  }
]
```

</details>

#### Learn more

* [AI Parser overview & quickstart](https://docs.scraperapi.com/ai-parser/overview-and-quickstart)
* [Understanding parsers & versions](https://docs.scraperapi.com/ai-parser/understanding-parsers-and-versions)
* [Pricing & limits](https://docs.scraperapi.com/ai-parser/pricing-and-limits)
* [Debugging & troubleshooting](https://docs.scraperapi.com/ai-parser/debugging-and-troubleshooting)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.scraperapi.com/integrations/automation-and-workflow-integrations/n8n-integration/ai-parser-less-than-greater-than-n8n.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.