# HTML to JSON Smart Parser (`parseforge/html-to-json-smart-parser`) Actor

Converts HTML from URLs, pasted content, or uploaded files into structured JSON using OpenAI. Specify fields or let AI auto-detect important data. Returns one flat JSON object per input.

- **URL**: https://apify.com/parseforge/html-to-json-smart-parser.md
- **Developed by:** [ParseForge](https://apify.com/parseforge) (community)
- **Categories:** AI, Developer tools, Automation
- **Features:** Limited permissions
- **Stats:** 58 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $2.23 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

[![ParseForge](https://raw.githubusercontent.com/ParseForge/apify-assets/main/banner-v4.webp)](https://apify.com/parseforge?fpr=vmoqkp)

### HTML to JSON Smart Parser

**Convert any HTML page or pasted HTML into clean, structured JSON with AI.** Provide a URL, paste HTML, or upload a file, and get back a flat JSON object with the fields you need. No coding, no selectors, no brittle parsing.

Turning messy HTML into usable JSON usually means writing custom parsers, maintaining XPath or CSS selectors, and fixing them every time the site changes. This actor uses an OpenAI model to read the HTML and extract the fields you ask for, or auto-detects the important ones. It works on any page, from product listings to articles to dashboards, and returns one consistent JSON object per input.

| Who uses it | What they scrape HTML to JSON for |
|---|---|
| Data engineers | Turn one-off HTML pages into JSON for pipelines without writing a custom scraper |
| Market researchers | Extract structured data from competitor pages or industry reports |
| No-code builders | Feed HTML into automation tools that expect JSON |
| SEO analysts | Pull structured content from pages to audit metadata or on-page elements |

### What it does

This actor fetches HTML from URLs, pasted content, or uploaded files, and uses an OpenAI model to convert it into a flat JSON object with the fields you specify or auto-detected fields.

- 🔗 **URL input:** paste one or more page URLs and the actor fetches the HTML for you
- 📋 **Paste HTML:** drop raw HTML directly into the input and get JSON back
- 📁 **File upload:** upload HTML files and provide their URLs for batch conversion
- 🤖 **AI extraction:** specify fields like title, price, or description, or let the model auto-detect what matters
- 🧠 **Custom prompt:** override the default system prompt to guide extraction for niche use cases

Results export to CSV, JSON, Excel, or XML, or straight from the API.

### What you can do with HTML to JSON data

**🛒 Extract product data from e-commerce pages.**

A dropshipper pastes a competitor product URL, asks for title, price, and images, and gets a clean JSON object to feed into their own store.

**📰 Turn articles into structured records.**

A content analyst uploads HTML files of news articles, specifies headline, author, and body, and receives one JSON row per article for their database.

**📊 Pull data from dashboards or reports.**

A business user pastes HTML from an internal report, asks for key metrics, and gets JSON they can load into a spreadsheet.

**🔍 Audit on-page SEO elements.**

An SEO specialist provides a list of URLs, requests title, meta description, and H1 tags, and receives a JSON dataset for a site-wide audit.

### Why choose this scraper

|  | What you get |
|---|---|
| **No selectors** | You never write CSS or XPath. The AI reads the page and finds the data |
| **Any HTML** | Works on product pages, articles, dashboards, and even malformed markup |
| **Flexible fields** | Ask for specific fields or let the model decide what is important |
| **Batch ready** | Feed multiple URLs or files in one run and get a dataset of JSON rows |

### How it compares

This actor uses AI to convert HTML to JSON without any selectors, while the competitors below require code or focus on article extraction.

| Feature | ParseForge | Cheerio Scraper | Smart Article Extractor |
|---|---|---|---|
| AI-based extraction without selectors | Yes | Not listed | Not listed |
| Paste raw HTML directly | Yes | Not listed | Not listed |
| Upload HTML files | Yes | Not listed | Not listed |
| Custom system prompt for extraction | Yes | Not listed | Not listed |
| Recursive crawling of websites | Not listed | Yes | Yes |
| Automatic article detection | Not listed | Not listed | Yes |

### Configure the run

Provide URLs, pasted HTML, or uploaded file URLs, and optionally list the fields you want extracted or a custom system prompt. The actor processes each input and returns one JSON object per page. The Input tab lists every parameter.

A first run with the defaults:

```json
{
  "url": [
    {
      "url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html"
    }
  ],
  "htmlFileUrl": [],
  "model": "gpt-4o-mini"
}
```

### Pricing

Pay-per-result: **$0.0025 per result** collected. You pay only for the results written to your dataset.

| Results collected | Approximate cost |
|---|---|
| 100 results | $0.25 |
| 1,000 results | $2.50 |
| 10,000 results | $25.00 |

New Apify accounts start with $5 in free credit.

### Free users

Free-plan runs return up to 10 results as a preview. [Upgrade your Apify plan](https://console.apify.com/sign-up?fpr=vmoqkp) to collect more results per run.

### Run it

1. [Create a free Apify account with $5 in credit](https://console.apify.com/sign-up?fpr=vmoqkp).
2. Open the [HTML to JSON Smart Parser](https://apify.com/parseforge/html-to-json-smart-parser?fpr=vmoqkp).
3. Set your inputs and any filters, then click **Start**.
4. Export the results as CSV, Excel, JSON, or XML from the **Dataset** tab.

Run it programmatically through the [Apify API](https://docs.apify.com/api/v2) (`run-sync-get-dataset-items`) or the [ApifyClient](https://docs.apify.com/api/client/js) for JavaScript and Python.

### Use with AI agents (MCP)

Give an AI agent live access to HTML to JSON through the Model Context Protocol. Add the Actor to Claude, Cursor, or any MCP client:

```bash
claude mcp add --transport http apify "https://mcp.apify.com?tools=parseforge/html-to-json-smart-parser"
```

Then prompt it in plain language to run the scraper and read back the results.

### Troubleshooting

**Why am I getting an error about the OpenAI API key?**

Make sure you have entered a valid OpenAI API key in the input. The key must have access to the model you selected. If the key is missing or invalid, the actor logs an error and skips the run.

**Why is the output JSON empty or missing fields?**

The model may not have found the fields you requested. Check that the HTML contains the data, and try specifying the fields explicitly in 'Fields to Extract'. You can also use a custom system prompt to guide the model.

**Why does the actor fail on some URLs?**

The actor uses a simple HTTP GET request. Some sites block non-browser requests or require JavaScript. If a URL fails, try fetching the HTML with a browser-based scraper and then paste the HTML into this actor.

**Why is the run slow?**

Each page requires an OpenAI API call, which can take a few seconds. If you are processing many pages, consider using a faster model like gpt-4o-mini or reducing the number of inputs.

**Can I process HTML files I have on my computer?**

Yes, upload the HTML files to Apify using the file upload button in the input, then provide the file URLs in the 'HTML file URLs' field. The actor will fetch and process them.

### FAQ

| Question | Answer |
|---|---|
| Do I need an OpenAI API key? | Yes, you must provide your own OpenAI API key in the input. The actor uses it to call the model for extraction. Without a key, the actor logs an error and skips processing. |
| What if I don't specify fields to extract? | The actor uses a smart default prompt that tells the model to identify and extract all important fields from the HTML. You will get a JSON object with the fields the model found. |
| Can I process multiple pages in one run? | Yes, you can provide multiple URLs or multiple HTML file URLs. Each input is processed separately and returned as one row in the dataset. |
| What models are supported? | You can choose from gpt-4o, gpt-4o-mini, gpt-4-turbo, and gpt-3.5-turbo. The default is gpt-4o-mini for a good balance of cost and quality. |
| Can I customize how the AI extracts data? | Yes, you can provide a custom system prompt in the input. This overrides the default prompt and lets you give specific instructions to the model. |
| Does this work with JavaScript-rendered pages? | No, the actor makes a simple HTTP GET request and does not execute JavaScript. If the page requires JS to render content, you should use a browser-based scraper like Puppeteer Scraper first and then feed the HTML here. |
| What output formats are supported? | The actor returns JSON objects in the dataset. You can export the dataset to CSV, JSON, Excel, or XML from the Apify platform. |
| Is there a limit on HTML size? | The actor can handle typical web pages, but very large HTML files may exceed the model's context window. If you encounter errors, try extracting only the relevant portion of the HTML. |
| Can I use this for free? | The actor itself runs on Apify, but you will incur OpenAI API costs based on the model and the amount of text processed. Apify platform usage may also apply. |
| What if the extraction returns wrong fields? | Try specifying the exact fields you want in the 'Fields to Extract' input, or provide a custom system prompt with clearer instructions. You can also switch to a more capable model like gpt-4o. |

### Related actors

Browse the full [ParseForge collection](https://apify.com/parseforge?fpr=vmoqkp) for more scrapers.

🆘 **Need help?** Email parseforge@protonmail.com with your run ID, your input, and what you expected.

⚠️ **Disclaimer.** This Actor is unofficial and is not affiliated with, endorsed by, or sponsored by OpenAI. It collects only publicly available data. You are responsible for using the collected data in compliance with the source's terms of service and applicable data-protection laws, including GDPR, CCPA, and PIPL. Do not use it to collect personal data unlawfully.

# Actor input Schema

## `url` (type: `array`):

URL(s) to fetch HTML content from. This will make a simple HTTP GET request to fetch the HTML. You can provide multiple URLs. Leave empty if pasting HTML or uploading files.

## `htmlContent` (type: `string`):

Paste your HTML content here to convert to JSON, if not provided, the AI will automatically extract all important fields it identifies.

## `htmlFileUrl` (type: `array`):

Upload HTML file(s) and paste their URL(s) here. You can provide multiple file URLs. Leave empty if using URLs or pasting HTML content. You can upload files using the file upload button in Apify Console.

## `openAIApiKey` (type: `string`):

Your OpenAI API key (if not provided it would return an error). You can get one from https://platform.openai.com/api-keys. If not provided, the actor will log an error and skip processing.

## `model` (type: `string`):

The OpenAI model to use for conversion. Options: gpt-5, gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo

## `fieldsToExtract` (type: `string`):

Specify which fields you want extracted from the HTML (e.g., \['title', 'price', 'description', 'images', 'specifications']). You can provide multiple field names. If not provided, the AI will automatically extract all important fields it identifies.

## `systemPrompt` (type: `string`):

Optional custom system prompt to guide the AI extraction. If not provided, a smart default prompt will be used that extracts meaningful information.

## Actor input object example

```json
{
  "url": [
    {
      "url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html"
    }
  ],
  "htmlFileUrl": [],
  "openAIApiKey": "",
  "model": "gpt-4o-mini",
  "systemPrompt": ""
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "url": [
        {
            "url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html"
        }
    ],
    "htmlFileUrl": [],
    "openAIApiKey": "",
    "model": "gpt-4o-mini",
    "systemPrompt": ""
};

// Run the Actor and wait for it to finish
const run = await client.actor("parseforge/html-to-json-smart-parser").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "url": [{ "url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html" }],
    "htmlFileUrl": [],
    "openAIApiKey": "",
    "model": "gpt-4o-mini",
    "systemPrompt": "",
}

# Run the Actor and wait for it to finish
run = client.actor("parseforge/html-to-json-smart-parser").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "url": [
    {
      "url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html"
    }
  ],
  "htmlFileUrl": [],
  "openAIApiKey": "",
  "model": "gpt-4o-mini",
  "systemPrompt": ""
}' |
apify call parseforge/html-to-json-smart-parser --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,parseforge/html-to-json-smart-parser"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/YSa1ctGggVBeejfsw/builds/3jBfRwDprjmMSVYAB/openapi.json