# Webpage Readability Grade - Main Content, 6 Formulas (`eliai/webpage-readability-grade`) Actor

Grade any URL's readability the honest way: main content extracted first (nav/footer/sidebar boilerplate stripped, <main>/<article> preferred), then Flesch, FK, Fog, SMOG, ARI, Coleman-Liau + level label. Up to 100 URLs per run. $0.002 per page, HTTP errors never charged.

- **URL**: https://apify.com/eliai/webpage-readability-grade.md
- **Developed by:** [Broke to Built](https://apify.com/eliai) (community)
- **Categories:** SEO tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.60 / 1,000 graded pages

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Webpage Readability Grade - Fetch, Extract Main Content, Score

Point it at any URL - get the readability grade of the page's actual content. It fetches the page, **extracts the main content first** (nav, header, footer, sidebar, and form boilerplate stripped; semantic `<main>`/`<article>` regions preferred), then scores what remains with six standard formulas. Up to 100 URLs per run, online, by API, or as an agent tool via Apify MCP.

That extraction step is the point: grade a raw page and the cookie banner, menu labels and footer links poison the sentence statistics. Here the grade reflects what a reader actually reads - and every record tells you which region was used and how many boilerplate blocks were removed.

Already holding clean text rather than a URL? Then the fetch and extraction are the only things you would be paying for here - score it yourself, or use any text-only analyzer.

### What you get

- **extraction** - `usedScope` (`main` / `article` / `body`) + `boilerplateBlocksRemoved`: proof of what was graded
- **scores** - Flesch Reading Ease, Flesch-Kincaid Grade, Gunning Fog, SMOG, ARI, Coleman-Liau
- **readingLevel** - plain-English label ("Middle School", "College"...)
- **stats** - sentences, words, syllables, complex words of the extracted content
- **Fail-soft**: an unfetchable URL or an HTTP error page never fails the run - it returns `{ok: false, error}` and is **never charged** (a 404 page is not graded and not billed).

### Input

```json
{ "urls": ["https://yourblog.com/post-1", "https://yourblog.com/post-2"], "maxUrls": 50 }
```

Or a single URL via `url` (scheme optional - `example.com/page` works).

### Output (real run)

```json
{
  "url": "https://en.wikipedia.org/wiki/Readability",
  "ok": true,
  "status": 200,
  "extraction": { "usedScope": "main", "boilerplateBlocksRemoved": 6 },
  "stats": { "sentences": 1419, "words": 7720, "syllables": 13739, "complexWords": 1570 },
  "scores": { "fleschReadingEase": 50.75, "fleschKincaidGrade": 7.53, "gunningFog": 10.31, "smog": 9.14, "ari": 6.2, "colemanLiau": 9.86 },
  "readingLevel": "Middle School"
}
```

### Pricing

**$0.002 per page graded** - one `page-scanned` event covering the fetch, the main-content
extraction and all six formulas. **No actor-start fee.** Unfetchable pages and HTTP-error pages are
never charged, so a batch with dead links only bills for the ones that graded.

A 100-page content audit costs **$0.20**. A single page costs $0.002.

#### Honest comparison

Measured from each actor's live pricing on **2026-08-15**:

| Actor | Price shape | 100 pages |
|---|---|---|
| `ninhothedev/readability-analyzer` | $0.00005 start + $0.0005 per item | $0.05 |
| **eliai/webpage-readability-grade** (this one) | $0.002 per page, no start fee | **$0.20** |
| `maximedupre/readability-analyzer` | $0.00005 per word analyzed | ~$5.00 at 1,000 words/page |
| `acclaimed_ashram/content-intelligence` | $0.00005 start + $0.01 per item | $1.00 |

Prices are not like-for-like and you should not treat them as such: what is priced in here is the
**fetch plus main-content extraction** before scoring, and `extraction.usedScope` +
`boilerplateBlocksRemoved` in every record so you can see what was graded. A cheaper analyzer that
scores the raw page is measuring the cookie banner and the footer along with the prose, and a
per-word price scales with exactly the thing you cannot control.

### When NOT to use this

- **You have the text already, not a URL.** The fetch and the main-content extraction are the
  entire reason this costs what it costs; scoring text you already hold is arithmetic you can run
  yourself.
- **Non-English content.** All six formulas use English syllable and word-length heuristics. They
  will happily return numbers for French or German text and those numbers mean nothing.
- **JavaScript-rendered pages.** The served HTML is parsed without a browser, so an SPA that
  assembles its article client-side yields a very low word count. That is reported honestly rather
  than failed, but the grade is not usable.
- **Comparing across formulas as if they agree.** They will not: on the same page Flesch-Kincaid,
  Gunning Fog and SMOG routinely differ by two or three grade levels because they weigh sentence
  length and syllables differently. Pick one, and track it over time.
- **Grading PDFs, docs, or feeds.** HTML pages only.
- **Treating a grade as a quality score.** Readability measures sentence and word complexity, not
  whether the writing is correct, useful, or good.

### Honest limits

- Static HTML fetch - JavaScript-rendered content (SPA pages that ship an empty shell) yields little text; such pages report low word counts honestly rather than failing.
- Main-content extraction is heuristic (semantic tags + boilerplate-tag removal, no headless browser): pages with non-semantic div-soup markup fall back to `body` scope with boilerplate tags stripped - `extraction.usedScope` always tells you which happened.
- English-calibrated formulas (syllable heuristics); scores on other languages are not meaningful.

### FAQ

**How is this different from a plain text readability analyzer?**
This one owns the URL problem: the fetch, HTTP handling, redirects, and main-content extraction all happen before a single formula runs. A text analyzer starts after you have already solved the hard part. If you have clean text in hand, you do not need this.

**Why does the extraction field matter?**
Trust. `usedScope: "main"` with 6 blocks removed means the grade came from the article body - not from "Home About Contact Privacy Cookie Settings" repeated in the stats.

**Can I audit a whole blog?**
Yes - batch up to 100 URLs per run, sort by `scores.fleschKincaidGrade`, rewrite the outliers.

**What grade should web content target?**
Flesch Reading Ease 60+ / grade <=9 for a general audience. Wikipedia's own Readability article scores 50.75 (borderline difficult) - fittingly ironic, and a real measured example.

**Why did some rows come back `ok: false`?**
DNS/timeout failures or HTTP 4xx/5xx responses - error pages are not graded. Recorded with the reason, never charged.

**How do I check the reading level of a web page?**
Pass the URL. You get six standard scores plus a plain-English `readingLevel` label, computed on the page's main content rather than the whole document. `extraction.usedScope` tells you which region was graded.

**What is a good Flesch Reading Ease score?**
For general web content, 60 or above (roughly grade 8-9) is the usual target; 30-50 reads as academic; below 30 is heavy going. Technical documentation for a specialist audience legitimately scores lower, which is why the six formulas and the raw `stats` are all returned instead of a single pass/fail.

**Which of the six formulas should I actually use?**
Pick one and stay with it. Flesch-Kincaid Grade is the most widely recognised in style guides; Gunning Fog is stricter about long words; SMOG is the standard in health communication; Coleman-Liau and ARI use character counts instead of syllables and so are more robust on unusual vocabulary. They will disagree by two or three grades on the same text - that is normal and is why trend beats absolute.

**Does it grade the whole page or just the article?**
Just the main content. Nav, header, footer, sidebar and form boilerplate are removed first, and semantic `<main>` / `<article>` regions are preferred. Every record reports `usedScope` and `boilerplateBlocksRemoved` so you can verify what was measured.

**Can I compare my pages against a competitor's?**
Yes - put both sets of URLs in the same run and sort by one score. That is the cheapest useful version of a content-quality audit: $0.002 per page, no crawling, no setup.

### Related actors

- [Webpage Text Extractor](https://apify.com/eliai/webpage-text-extractor) - the extracted content itself, as Markdown or text
- [Sitemap URL Extractor](https://apify.com/eliai/sitemap-url-extractor) - get the URL list to audit in the first place
- [Webpage Links Extractor](https://apify.com/eliai/webpage-links-extractor) - every link on the same pages
- [SEO Audit Report](https://apify.com/eliai/seo-audit-report) - the broader technical pass on a page

Built by [Broke to Built](https://broke2builtai.com).

### Use from code or AI agents

```bash
curl -s "https://api.apify.com/v2/acts/EliAI~webpage-readability-grade/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -X POST -H 'Content-Type: application/json' \
  -d '{"url": "https://yourdomain.com/your-article"}'
```

Agents: connect [Apify MCP](https://mcp.apify.com) and call the `EliAI/webpage-readability-grade` tool.

- **Capability:** fetch one or many URLs, extract main content (boilerplate stripped), grade with 6 readability formulas
- **Required input:** `url` (string) or `urls` (array)
- **Returns:** one record per URL; `scores` + `readingLevel` + `extraction` summarize it
- **Bounded:** 100 URLs per run; failures isolate per URL
- **Side effects:** none (one GET per page)

### For AI agents

This Actor is built to be called by software, not just by people.

- **Mount it directly as an MCP tool** — no Store search, no ranking, just this one tool:
  `https://mcp.apify.com/?actors=eliai/webpage-readability-grade`
- **Or call it over HTTP** and get the results in the same request:
  `POST https://api.apify.com/v2/acts/eliai~webpage-readability-grade/run-sync-get-dataset-items`
- **Pay with x402, without an Apify account.** This Actor is whitelisted for agentic payments, so an agent holding USDC on Base can buy a prepaid token and spend it here. The minimum purchase is $1, the token balance is an absolute spending cap, and it expires 14 days after purchase.
- **Costs are predictable before you call.** Pricing is pay-per-event (see Pricing above), so an agent can budget a run in advance instead of discovering the bill afterwards.
- **Send only the field you mean.** If you pass the bulk field, it is used on its own; the single-value field is a fallback, never merged into your request. You are charged for the items you sent and nothing else.

# Actor input Schema

## `url` (type: `string`):

A single web page URL to grade for readability.

## `urls` (type: `array`):

Multiple web page URLs to grade. When you set this, it is used on its own and the single-value field above is ignored, so you are only charged for the items you sent.

## `maxUrls` (type: `integer`):

Maximum number of URLs to process in one run.

## Actor input object example

```json
{
  "url": "https://en.wikipedia.org/wiki/Readability",
  "urls": [],
  "maxUrls": 25
}
```

# Actor output Schema

## `results` (type: `string`):

Every item this run produced, as JSON.

## `resultsCsv` (type: `string`):

The same items as a spreadsheet-ready CSV.

# 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": "https://en.wikipedia.org/wiki/Readability"
};

// Run the Actor and wait for it to finish
const run = await client.actor("eliai/webpage-readability-grade").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": "https://en.wikipedia.org/wiki/Readability" }

# Run the Actor and wait for it to finish
run = client.actor("eliai/webpage-readability-grade").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": "https://en.wikipedia.org/wiki/Readability"
}' |
apify call eliai/webpage-readability-grade --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,eliai/webpage-readability-grade"
        }
    }
}

```

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/Er6b8yIKJcDOYPxM0/builds/leagtSh7ciR6oCaxD/openapi.json