# Parser Presets

You can **save**, **reuse**, and **modify** custom parsing instructions through the Web Scraper API. Once you create a parser preset, we'll host it on our system, enabling you to reference it in your scraping jobs via the `parser_preset` parameter in the payload.

This feature offers several **key capabilities**:

* Save and manage your own parsers on our system
* Easily reuse presets across multiple scraping jobs
* Create, retrieve, update, delete, and list all presets
* Access performance and usage statistics of a preset
* Adapt to changing sites using self-healing presets

## API reference

**Endpoint:** `https://data.oxylabs.io/v1/parsers/presets`

The table lists each available operation and its endpoint path:

<table><thead><tr><th width="247.30859375">Action</th><th width="152.23828125">Request Method</th><th>Path</th></tr></thead><tbody><tr><td><strong>Create</strong> a preset</td><td><code>POST</code></td><td><code>/v1/parsers/presets</code></td></tr><tr><td><strong>Retrieve</strong> a preset</td><td><code>GET</code></td><td><code>/v1/parsers/presets/{preset_name}</code></td></tr><tr><td><strong>Update</strong> a preset</td><td><code>PUT</code></td><td><code>/v1/parsers/presets/{preset_name}</code></td></tr><tr><td><strong>Delete</strong> a preset</td><td><code>DELETE</code></td><td><code>/v1/parsers/presets/{preset_name}</code></td></tr><tr><td><strong>List all</strong> presets</td><td><code>GET</code></td><td><code>/v1/parsers/presets</code></td></tr><tr><td><strong>View usage</strong> and <strong>performance</strong> statistics</td><td><code>GET</code></td><td><code>/v1/parsers/presets/{preset_name}/stats</code></td></tr><tr><td><strong>Track self-healing</strong> changes</td><td><code>GET</code></td><td><code>/v1/parsers/presets/{parser_name}/changelog</code></td></tr></tbody></table>

## Enable self-healing

Parser presets are equipped with the self-healing function, which helps maintain the parsers and their success rates as websites change. When enabled, parser presets **automatically repair themselves** and adjust parsing instructions in the background with no additional manual input.

To **enable self-healing** for your custom parser preset, include the following mandatory parameters when creating or updating a preset:

<table><thead><tr><th width="222.90234375">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>self_heal</code></td><td>Turns on the self-healing functionality when set to <code>True</code>.</td></tr><tr><td><code>prompt_schema</code></td><td>A JSON schema describing the required parser output. You can automatically create the schema when <a href="generating-parsing-instructions-via-api">generating parsers with API</a>.</td></tr><tr><td><code>urls</code></td><td>A list of up to 5 URLs of the same page type. We recommend providing 3-5 URLs to help the parser adapt to different layouts and improve parsing accuracy.</td></tr></tbody></table>

<details>

<summary>Payload sample</summary>

The payload example shown here enables self-healing by updating an existing preset.

**Endpoint:** `PUT https://data.oxylabs.io/v1/parsers/presets/{preset_name}`

```json
{
    "self_heal": true,
    "urls": ["https://sandbox.oxylabs.io/products"],
    "prompt_schema": {
        "properties": {
            "product_titles": {
                "description": "Title of each product.",
                "items": {
                    "type": "string"
                },
                "maxItems": 5,
                "title": "Product Titles",
                "type": "array"
            }
        },
        "required": [
            "product_titles"
        ],
        "title": "Fields",
        "type": "object"
    }
}
```

</details>

## Usage examples

### Create a preset

**Endpoint:** `POST https://data.oxylabs.io/v1/parsers/presets`

**Payload:**

```json
{
    "name": "my_new_parser",
    "description": "Extract text from all H4 elements on the page.",
    "parsing_instructions": {
        "titles": {
            "_fns": [
                {
                    "_args": ["//h4/text()"],
                    "_fn": "xpath"
                }
            ]
        }
    }
}
```

<details>

<summary>Output</summary>

```json
{
    "id": 421947,
    "name": "my_new_parser",
    "description": "Extract text from all H4 elements on the page.",
    "prompt_text": null,
    "prompt_schema": null,
    "urls": [],
    "render": false,
    "parsing_instructions": {
        "titles": {
            "_fns": [
                {
                    "_args": [
                        "//h4/text()"
                    ],
                    "_fn": "xpath"
                }
            ]
        }
    },
    "self_heal": false,
    "heal_status": "disabled",
    "last_healed_at": null,
    "created_at": "2025-10-27 11:40:22",
    "updated_at": "2025-10-27 11:40:22"
}
```

</details>

### Use a preset

**Endpoint:** `POST https://realtime.oxylabs.io/v1/queries`

**Payload:**

```json
{
    "source": "universal",
    "url": "https://sandbox.oxylabs.io/products",
    "parse": true,
    "parser_preset": "my_new_parser"
}
```

<details>

<summary>Output</summary>

```json
{
    "results": [
        {
            "content": {
                "titles": [
                    "The Legend of Zelda: Ocarina of Time",
                    "Super Mario Galaxy",
                    "Super Mario Galaxy 2",
                    "Metroid Prime",
                    "Super Mario Odyssey",
                    "Halo: Combat Evolved",
                    "The House in Fata Morgana - Dreams of the Revenants Edition -",
                    "NFL 2K1",
                    "Uncharted 2: Among Thieves",
                    "Tekken 3",
                    "The Legend of Zelda: The Wind Waker",
                    "Gran Turismo",
                    "Metal Gear Solid 2: Sons of Liberty",
                    "Grand Theft Auto Double Pack",
                    "Baldur's Gate II: Shadows of Amn",
                    "Tetris Effect: Connected",
                    "The Legend of Zelda Collector's Edition",
                    "Gran Turismo 3: A-Spec",
                    "The Legend of Zelda: A Link to the Past",
                    "The Legend of Zelda: Majora's Mask",
                    "The Last of Us",
                    "Persona 5 Royal",
                    "The Last of Us Remastered",
                    "The Legend of Zelda: Ocarina of Time 3D",
                    "Chrono Cross",
                    "Gears of War",
                    "Sid Meier's Civilization II",
                    "Halo 3",
                    "Ninja Gaiden Black",
                    "Super Mario Advance 4: Super Mario Bros. 3",
                    "Jet Grind Radio",
                    "Grim Fandango"
                ],
                "parse_status_code": 12000
            },
            "created_at": "2025-10-27 11:41:18",
            "updated_at": "2025-10-27 11:41:19",
            "page": 1,
            "url": "https://sandbox.oxylabs.io/products",
            "job_id": "7388540292158203905",
            "is_render_forced": false,
            "status_code": 200,
            "type": "parsed",
            "parser_type": "preset",
            "parser_preset": "my_new_parser"
        }
    ]
}
```

</details>

### Retrieve a preset

**Endpoint:** `GET https://data.oxylabs.io/v1/parsers/presets/{preset_name}`

<details>

<summary>Output</summary>

```json
{
    "id": 421947,
    "name": "my_new_parser",
    "description": "Extract text from all H4 elements on the page.",
    "prompt_text": null,
    "prompt_schema": null,
    "urls": [],
    "render": false,
    "parsing_instructions": {
        "titles": {
            "_fns": [
                {
                    "_args": [
                        "//h4/text()"
                    ],
                    "_fn": "xpath"
                }
            ]
        }
    },
    "self_heal": false,
    "heal_status": "disabled",
    "last_healed_at": null,
    "created_at": "2025-10-27 11:40:22",
    "updated_at": "2025-10-27 11:40:22"
}
```

</details>

### Update a preset

**Endpoint:** `PUT https://data.oxylabs.io/v1/parsers/presets/{preset_name}`

Define the fields of the preset you want to update. In the following example, only the `parsing_instructions` will get updated.

**Payload:**

```json
{
    "parsing_instructions": {
        "titles": {
            "_fns": [
                {
                    "_args": ["//h4/text()"],
                    "_fn": "xpath"
                }
            ]
        },
        "prices": {
            "_fns": [
                {
                    "_args": [".price-wrapper"],
                    "_fn": "css"
                },
                {"_fn": "element_text"}
            ]
        }
    }
}
```

<details>

<summary>Output</summary>

```json
{
    "id": 421947,
    "name": "my_new_parser",
    "description": "Extract text from all H4 elements on the page.",
    "prompt_text": null,
    "prompt_schema": null,
    "urls": [],
    "render": false,
    "parsing_instructions": {
        "prices": {
            "_fns": [
                {
                    "_args": [
                        ".price-wrapper"
                    ],
                    "_fn": "css"
                },
                {
                    "_fn": "element_text"
                }
            ]
        },
        "titles": {
            "_fns": [
                {
                    "_args": [
                        "//h4/text()"
                    ],
                    "_fn": "xpath"
                }
            ]
        }
    },
    "self_heal": false,
    "heal_status": "disabled",
    "last_healed_at": null,
    "created_at": "2025-10-27 11:40:22",
    "updated_at": "2025-10-27 11:44:24"
}
```

</details>

### Delete a preset

**Endpoint:** `DELETE https://data.oxylabs.io/v1/parsers/presets/{preset_name}`

### List all presets

**Endpoint:** `GET https://data.oxylabs.io/v1/parsers/presets`

<details>

<summary>Output</summary>

```json
[
    {
        "id": 421950,
        "name": "books_parser",
        "description": "Parses all book titles on the page.",
        "prompt_text": null,
        "prompt_schema": null,
        "urls": [],
        "render": false,
        "parsing_instructions": {
            "titles": {
                "_fns": [
                    {
                        "_args": [
                            "//h3//text()"
                        ],
                        "_fn": "xpath"
                    }
                ]
            }
        },
        "self_heal": false,
        "heal_status": "disabled",
        "last_healed_at": null,
        "created_at": "2025-10-27 11:46:59",
        "updated_at": "2025-10-27 11:46:59"
    },
    {
        "id": 421947,
        "name": "my_new_parser",
        "description": "Extract text from all H4 elements on the page.",
        "prompt_text": null,
        "prompt_schema": null,
        "urls": [],
        "render": false,
        "parsing_instructions": {
            "titles": {
                "_fns": [
                    {
                        "_args": [
                            "//h4/text()"
                        ],
                        "_fn": "xpath"
                    }
                ]
            }
        },
        "self_heal": false,
        "heal_status": "disabled",
        "last_healed_at": null,
        "created_at": "2025-10-27 11:40:22",
        "updated_at": "2025-10-27 11:45:20"
    }
]
```

</details>

### View statistics

**Endpoint:** `GET https://data.oxylabs.io/v1/parsers/presets/{preset_name}/stats`

<details>

<summary>Output</summary>

```json
{
    "total_results": 9,
    "successful_results": 9,
    "success_rate": 100,
    "success_rate_by_path": {
        "titles": 100
    }
}
```

</details>

You can **filter results by date and time** using the `date_from` and/or `date_to` URL parameters. Use the format `YYYY-MM-DDTHH`, where `T` indicates the time, and `HH` is the hour in a 24-hour format.

For example, to get statistics from 9 AM to 2 PM on August 5, 2025:

```url
https://data.oxylabs.io/v1/parsers/presets/{preset_name}/stats?date_from=2025-08-05T9&date_to=2025-08-05T14
```

### Track self-healing changes

**Endpoint:** `GET https://data.oxylabs.io/v1/parsers/presets/{preset_name}/changelog`

Our system automatically logs self-healing activity. You can access this historical log to review all modifications made by the self-healing function.


---

# 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://developers.oxylabs.io/scraping-solutions/web-scraper-api/features/custom-parser/parser-presets.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.