# Overview & Quickstart

### Overview

The `AI Parser` helps you to turn raw HTML responses from a website of your choice into clean, structured data. Feed it a few example URLs with the same structure: for example three product pages from a catalog. The `AI Parser` will generate a custom parser, that will extract the important data fields (or the ones you specify) from *any similar* page on that site (domain), automatically.

**Base URL:** `https://aiparser.scraperapi.com`

#### How it works in 3 steps

1. **Train** - send a few example URLs (**up to 3**) of the same page type (e.g. three product pages) to `POST /parsers` 
2. **Wait** - the system generates a parser tailored to the page’s layout.
3. **Parse** - send any similar URL to `GET /parse/{parser_id}` and get structured data back.

#### Authentication

Every endpoint needs an `api_key`. Pass it in the request body for `POST`/`PATCH`, or as a query parameter for `GET`/`DELETE` operations.

### Quickstart

1. Create a parser

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://aiparser.scraperapi.com/parsers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quotes_Parser",
    "api_key": "API_KEY",
    "urls": [
      "http://quotes.toscrape.com/page/1/",
      "http://quotes.toscrape.com/page/2/",
      "http://quotes.toscrape.com/page/3/"
    ]
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://aiparser.scraperapi.com/parsers"

payload = {
    "name": "Quotes_Parser",
    "api_key": "API_KEY",
    "urls": [
        "http://quotes.toscrape.com/page/1/",
        "http://quotes.toscrape.com/page/2/",
        "http://quotes.toscrape.com/page/3/"
    ]
}

headers = {
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.status_code)
print(response.text)
```

{% endtab %}

{% tab title="NodeJS" %}

```javascript
const url = "https://aiparser.scraperapi.com/parsers";

const payload = {
  name: "Quotes_Parser",
  api_key: "API_KEY",
  urls: [
    "http://quotes.toscrape.com/page/1/",
    "http://quotes.toscrape.com/page/2/",
    "http://quotes.toscrape.com/page/3/"
  ]
};

async function createParser() {
  try {
    const response = await fetch(url, {
      method: "POST",
      headers: {
        "Content-Type": "application/json"
      },
      body: JSON.stringify(payload)
    });

    const data = await response.json();

    console.log(response.status);
    console.log(data);
  } catch (error) {
    console.error(error);
  }
}

createParser();
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$url = "https://aiparser.scraperapi.com/parsers";

$postData = json_encode([
    "name" => "Quotes_Parser",
    "api_key" => "API_KEY",
    "urls" => [
        "http://quotes.toscrape.com/page/1/",
        "http://quotes.toscrape.com/page/2/",
        "http://quotes.toscrape.com/page/3/"
    ]
]);

$headers = [
    "Content-Type: application/json"
];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$response = curl_exec($ch);

curl_close($ch);

print_r($response);
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require 'net/http'
require 'json'

uri = URI('https://aiparser.scraperapi.com/parsers')

body = {
  "name" => "Quotes_Parser",
  "api_key" => "API_KEY",
  "urls" => [
    "http://quotes.toscrape.com/page/1/",
    "http://quotes.toscrape.com/page/2/",
    "http://quotes.toscrape.com/page/3/"
  ]
}

response = Net::HTTP.post(
  uri,
  body.to_json,
  "Content-Type" => "application/json"
)

print(response.body)
```

{% endtab %}

{% tab title="Java" %}

```java
import java.io.*;
import java.net.*;
import java.nio.charset.StandardCharsets;

public class Main {
    public static void main(String[] args) {
        try {
            HttpURLConnection conn = (HttpURLConnection)
                new URL("https://aiparser.scraperapi.com/parsers").openConnection();

            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setDoOutput(true);

            String body = "{"
                + "\"name\":\"Quotes_Parser\","
                + "\"api_key\":\"API_KEY\","
                + "\"urls\":["
                + "\"http://quotes.toscrape.com/page/1/\","
                + "\"http://quotes.toscrape.com/page/2/\","
                + "\"http://quotes.toscrape.com/page/3/\""
                + "]"
                + "}";

            conn.getOutputStream().write(body.getBytes(StandardCharsets.UTF_8));

            BufferedReader in = new BufferedReader(
                new InputStreamReader(
                    conn.getResponseCode() == 200
                        ? conn.getInputStream()
                        : conn.getErrorStream()
                )
            );

            StringBuilder res = new StringBuilder();
            String line;

            while ((line = in.readLine()) != null) {
                res.append(line);
            }

            System.out.println(res);

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

{% endtab %}
{% endtabs %}

**Response**

```json
{
    "id": "parser_id",
    "version": 0
}
```

2. Check the Parser's state

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET \
  "https://aiparser.scraperapi.com/parsers/<PARSER_ID>?api_key=API_KEY"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://aiparser.scraperapi.com/parsers/<PARSER_ID>"

params = {
    "api_key": "API_KEY"
}

response = requests.get(url, params=params)

print(response.status_code)
print(response.text)
```

{% endtab %}

{% tab title="NodeJS" %}

```javascript
const parserId = "PARSER_ID";
const apiKey = "API_KEY";

const url = `https://aiparser.scraperapi.com/parsers/${parserId}?api_key=${apiKey}`;

async function getParser() {
  try {
    const response = await fetch(url);

    const data = await response.json();

    console.log("Status:", response.status);

    // IMPORTANT: force full expansion in console
    console.log(JSON.stringify(data, null, 2));
  } catch (error) {
    console.error("Error:", error);
  }
}

getParser();
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$parserId = "PARSER_ID";
$apiKey = "API_KEY";

$url = "https://aiparser.scraperapi.com/parsers/$parserId?api_key=$apiKey";

$response = file_get_contents($url);

echo $response;
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require 'net/http'
require 'uri'

parser_id = "PARSER_ID"
api_key = "API_KEY"

uri = URI("https://aiparser.scraperapi.com/parsers/#{parser_id}?api_key=#{api_key}")

response = Net::HTTP.get(uri)

print(response)
```

{% endtab %}

{% tab title="Java" %}

```java
import java.io.*;
import java.net.*;

public class Main {
    public static void main(String[] args) {
        try {
            String parserId = "PARSER_ID";
            String apiKey = "API_KEY";

            URL url = new URL(
                "https://aiparser.scraperapi.com/parsers/" +
                parserId +
                "?api_key=" +
                apiKey
            );

            BufferedReader in = new BufferedReader(
                new InputStreamReader(url.openStream())
            );

            StringBuilder response = new StringBuilder();
            String line;

            while ((line = in.readLine()) != null) {
                response.append(line);
            }

            in.close();

            System.out.println(response.toString());

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

{% endtab %}
{% endtabs %}

<details>

<summary><strong>Example Responses</strong></summary>

Generating

```json
{"name":"Quotes Parser","created_at":"2026-05-08T14:28:42.283Z","generated_at":null,"status":"GENERATING","error":null,"example_result":null,"fields":[],"version":0}
```

Failed

```json
{"name":"My_Product_Parser","created_at":"2026-05-08T14:17:31.657Z","generated_at":"2026-05-08T14:17:34.961Z","status":"FAILED","error":"DownloadError: Failed to download https://example.com/product-01 after 3 retries","example_result":null}
```

Finished

```json
{"name":"Quotes Parser","created_at":"2026-05-08T14:28:42.283Z","generated_at":"2026-05-08T14:32:48.882Z","status":"FINISHED","error":null,"example_result"[{.......}]}
```

</details>

3. Parse similar URL

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request GET \
  --url "https://aiparser.scraperapi.com/parse/<PARSER_ID>?api_key=API_KEY&url=https://quotes.toscrape.com/page/4/"
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

parser_id = "PARSER_ID"
api_key = "API_KEY"
target_url = "https://quotes.toscrape.com/page/4/"

url = f"https://aiparser.scraperapi.com/parse/{parser_id}"

params = {
    "api_key": api_key,
    "url": target_url
}

response = requests.get(url, params=params)

print(response.status_code)
print(response.text)
```

{% endtab %}

{% tab title="NodeJS" %}

```javascript
const parserId = "PARSER_ID";
const apiKey = "API_KEY";
const targetUrl = "https://quotes.toscrape.com/page/4/";

const url = new URL(`https://aiparser.scraperapi.com/parse/${parserId}`);

url.searchParams.append("api_key", apiKey);
url.searchParams.append("url", targetUrl);

async function run() {
  const response = await fetch(url);

  const data = await response.text();

  console.log(response.status);
  console.log(data);
}

run();
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php

$parserId = "PARSER_ID";
$apiKey = "API_KEY";
$targetUrl = "https://quotes.toscrape.com/page/4/";

$url = "https://aiparser.scraperapi.com/parse/$parserId" .
       "?api_key=" . urlencode($apiKey) .
       "&url=" . urlencode($targetUrl);

$response = file_get_contents($url);

echo $response;
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require 'net/http'
require 'uri'

parser_id = "PARSER_ID"
api_key = "API_KEY"
target_url = "https://quotes.toscrape.com/page/4/"

uri = URI("https://aiparser.scraperapi.com/parse/#{parser_id}")

uri.query = URI.encode_www_form(
  api_key: api_key,
  url: target_url
)

response = Net::HTTP.get_response(uri)

print(response.body)
```

{% endtab %}

{% tab title="Java" %}

```java
import java.io.*;
import java.net.*;

public class Main {
    public static void main(String[] args) {
        try {
            String parserId = "PARSER_ID";
            String apiKey = "API_KEY";
            String targetUrl = "https://quotes.toscrape.com/page/4/";

            String query = String.format(
                "api_key=%s&url=%s",
                URLEncoder.encode(apiKey, "UTF-8"),
                URLEncoder.encode(targetUrl, "UTF-8")
            );

            URL url = new URL(
                "https://aiparser.scraperapi.com/parse/" + parserId + "?" + query
            );

            BufferedReader in = new BufferedReader(
                new InputStreamReader(url.openStream())
            );

            StringBuilder response = new StringBuilder();
            String line;

            while ((line = in.readLine()) != null) {
                response.append(line);
            }

            in.close();

            System.out.print(response.toString());

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

{% endtab %}
{% endtabs %}

<details>

<summary><strong>Example Response</strong></summary>

```json
{
  "header": [
    {
      "title": "Quotes to Scrape",
      "login_link": "Login"
    }
  ],
  "quotes": [
    {
      "text": "“The more that you read, the more things you will know. The more that you learn, the more places you'll go.”",
      "author": "Dr. Seuss",
      "about_link": "/author/Dr-Seuss",
      "tags": [
        { "tag": "learning" }
      ]
    },
    {
      "text": "“Of course it is happening inside your head, Harry, but why on earth should that mean that it is not real?”",
      "author": "J.K. Rowling",
      "about_link": "/author/J-K-Rowling",
      "tags": [
        { "tag": "dumbledore" }
      ]
    },
    {
      "text": "“The truth is, everyone is going to hurt you. You just got to find the ones worth suffering for.”",
      "author": "Bob Marley",
      "about_link": "/author/Bob-Marley",
      "tags": [
        { "tag": "friendship" }
      ]
    },
    {
      "text": "“Not all of us can do great things. But we can do small things with great love.”",
      "author": "Mother Teresa",
      "about_link": "/author/Mother-Teresa",
      "tags": [
        { "tag": "misattributed-to-mother-teresa" }
      ]
    },
    {
      "text": "“To the well-organized mind, death is but the next great adventure.”",
      "author": "J.K. Rowling",
      "about_link": "/author/J-K-Rowling",
      "tags": [
        { "tag": "death" }
      ]
    },
    {
      "text": "“All you need is love. But a little chocolate now and then doesn't hurt.”",
      "author": "Charles M. Schulz",
      "about_link": "/author/Charles-M-Schulz",
      "tags": [
        { "tag": "chocolate" }
      ]
    },
    {
      "text": "“We read to know we're not alone.”",
      "author": "William Nicholson",
      "about_link": "/author/William-Nicholson",
      "tags": [
        { "tag": "misattributed-to-c-s-lewis" }
      ]
    },
    {
      "text": "“Any fool can know. The point is to understand.”",
      "author": "Albert Einstein",
      "about_link": "/author/Albert-Einstein",
      "tags": [
        { "tag": "knowledge" }
      ]
    },
    {
      "text": "“I have always imagined that Paradise will be a kind of library.”",
      "author": "Jorge Luis Borges",
      "about_link": "/author/Jorge-Luis-Borges",
      "tags": [
        { "tag": "books" }
      ]
    },
    {
      "text": "“It is never too late to be what you might have been.”",
      "author": "George Eliot",
      "about_link": "/author/George-Eliot",
      "tags": [
        { "tag": "inspirational" }
      ]
    }
  ],
  "pagination": [
    {
      "previous": "/page/3/",
      "next": "/page/5/"
    }
  ],
  "top_tags": [
    { "top_tag": "love" },
    { "top_tag": "inspirational" },
    { "top_tag": "life" },
    { "top_tag": "humor" },
    { "top_tag": "books" },
    { "top_tag": "reading" },
    { "top_tag": "friendship" },
    { "top_tag": "friends" },
    { "top_tag": "truth" },
    { "top_tag": "simile" }
  ],
  "footer": [
    {
      "credits": "Made with ❤ by Zyte"
    }
  ]
}
```

</details>

#### What's next

* Understand how [prasers and versions work](/ai-parser/understanding-parsers-and-versions.md).
* Browse the [endpoints](/ai-parser/endpoints.md).
* Check out [Pricing & Limits](/ai-parser/pricing-and-limits.md).
* Hit a wall? Check out [Debugging & Troubleshooting](/ai-parser/debugging-and-troubleshooting.md) section.


---

# 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/overview-and-quickstart.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.