# Text Readability Analyzer - 6 Formulas, Grade + Tips (`eliai/text-readability-analyzer`) Actor Score up to 100 texts per run with Flesch, Flesch-Kincaid, Gunning Fog, SMOG, ARI and Coleman-Liau + consensus grade, audience label and concrete fix-it tips. $0.0004 per text all six formulas, no start fee, word-free inputs never charged — vs $0.0005-$0.015 measured incumbents. - **URL**: https://apify.com/eliai/text-readability-analyzer.md - **Developed by:** [Broke to Built](https://apify.com/eliai) (community) - **Categories:** SEO tools, AI - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.32 / 1,000 scored texts 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 ## Readability Score API - Flesch, Flesch-Kincaid, Gunning Fog, SMOG, ARI, Coleman-Liau **Score any text with all six standard readability formulas at once**, plus a consensus grade level, a plain-English audience label, and specific suggestions for what to fix. Up to 100 texts per run. $0.0004 per text. Inputs with no words are recorded free. Editors gate on grade 8 to 9. Plain-language regulations require a measurable level. SEO teams audit whole content libraries for reading difficulty. One run answers "how hard is this to read, and exactly which lever is making it hard?" ### What you get Per text, one record with these exact fields: - `readingLevel` - `Very Easy` through `Extremely Difficult` - `audience` - who can read it, in plain words - `scores` - `fleschReadingEase`, `fleschKincaidGrade`, `gunningFog`, `smog`, `automatedReadabilityIndex`, `colemanLiauIndex`, and `consensusGrade` - `stats` - `sentences`, `words`, `paragraphs`, `syllables`, `characters`, `uniqueWords`, `complexWords`, `avgWordsPerSentence`, `avgSyllablesPerWord`, `pctComplexWords` - `suggestion` - which lever to pull, with the measured number that triggered it - `textPreview` - the first 60 characters, so you can tell records apart - `error` - present instead of scores when the input had no words. Never charged. `consensusGrade` is the average of the five grade-producing formulas. It is the number to gate on. ### Example 1: dense professional prose Input: ```json { "text": "Notwithstanding the aforementioned contractual stipulations, the counterparty shall indemnify and hold harmless the disclosing entity from any consequential liabilities arising from unauthorized dissemination of proprietary informational assets." } ``` Output (real run, 2026-08-15): ```json { "ok": true, "readingLevel": "Extremely Difficult", "audience": "Professional / academic", "scores": { "fleschReadingEase": -49.3, "fleschKincaidGrade": 26.8, "gunningFog": 33, "smog": 25.3, "automatedReadabilityIndex": 29.9, "colemanLiauIndex": 30.4, "consensusGrade": 29.1 }, "stats": { "sentences": 1, "words": 27, "paragraphs": 1, "syllables": 73, "characters": 217, "uniqueWords": 24, "complexWords": 15, "avgWordsPerSentence": 27, "avgSyllablesPerWord": 2.7, "pctComplexWords": 55.6 }, "suggestion": "Aim for Flesch Reading Ease 60+ (plain English) for a general web audience. Sentences average 27 words - break long sentences into shorter ones (target <20). 55.6% of words have 3+ syllables - swap in simpler synonyms. Word complexity is high - prefer shorter, common words." } ``` A negative Flesch score and a consensus grade of 29 is the formulas saying "no general audience will finish this sentence". The `suggestion` names the two causes with their measured values. ### Example 2: plain writing, for contrast Input: ```json { "text": "The cat sat on the mat. It was warm. The sun was out. We were happy. It was a good day." } ``` Output (real run, 2026-08-15, trimmed): ```json { "ok": true, "readingLevel": "Very Easy", "audience": "5th grade - easily understood by an 11-year-old", "scores": { "fleschReadingEase": 113.9, "fleschKincaidGrade": -1.6, "gunningFog": 1.7, "consensusGrade": 0 }, "stats": { "sentences": 5, "words": 21, "avgWordsPerSentence": 4.2, "pctComplexWords": 0 }, "suggestion": "Readability is solid for a general audience - no major changes needed." } ``` Similar length to Example 1, opposite verdict: 113.9 against -49.3 on the same Flesch scale. The release test asserts that a simple text and a dense one separate by more than 40 Flesch points on every deploy, so the formulas demonstrably discriminate. Note that grade scores can go negative on very simple text - that is the formulas working, not an error. ### Example 3: auditing a content library Input: ```json { "texts": ["Article one body...", "Article two body...", "Article three body..."], "maxTexts": 100 } ``` One record and one charge per text. Sort by `consensusGrade` descending and the top of that list is your rewrite queue. **When `texts` is filled, the single `text` field is ignored** - you are charged for the texts you listed and nothing else. ### Pricing **$0.0004 per text scored.** No start fee. One event covers one text scored across all six formulas, with the consensus grade, the audience label, the full statistics block and the suggestion - asking for six formulas costs the same as asking for one, because you always get all six. Texts with no words are recorded and never charged. A 1,000-page content audit costs $0.40. A 10,000-page one costs $4. Honest comparison, read from the Apify Store on 2026-08-07: | Actor | Pricing | Cost of 1,000 texts | |---|---|---| | **This actor** | **$0.0004 per text** | **$0.40** | | ninhothedev/readability-analyzer | $0.00005 start + $0.0005 per item | ~$0.50 | | perryay/content-readability-analyzer | $0.015 per analysis | $15 | ### When NOT to use this - **Any language other than English.** The syllable counter is an English heuristic, and every one of these formulas was calibrated on English. Scores on Spanish, German or Chinese text are numbers without meaning. Detect the language first (`EliAI/text-language-detector`) and only score English. - **Judging whether writing is good.** These formulas measure sentence length and word length. A grammatical nonsense sentence made of short words scores "Very Easy". Use this as the mechanical gate before a human edit, never instead of one. - **Short texts, if you care about SMOG specifically.** SMOG was designed for samples of 30 or more sentences. It is reported regardless, but on a paragraph, weight `consensusGrade` instead. - **Technical writing judged against a general-audience target.** A correct API reference is full of long precise nouns and will always score badly. Gate technical docs against their own baseline, not against grade 8. - **Counting words only.** If you do not need the formulas, `EliAI/text-statistics` is the cheaper, simpler tool for that. ### Honest limits - English only, as above. - Syllable counting is heuristic (roughly 90%+ per-word accuracy); paragraph totals are reliable, individual rare words can be off by one. - Sentences split on `.`, `!`, `?`; abbreviation-heavy text over-counts sentences slightly, which nudges the grade down a little. - Up to 100 texts per run. ### FAQ **Which score should I gate my content on?** `consensusGrade`, the average of the five grade-level formulas - it is the most stable single number because it smooths out each formula's individual quirks. For general web content, gate at 9 or below. For plain-language legal or medical requirements, 8 or below. **What is a good Flesch Reading Ease score?** 60 to 70 is plain English and the usual web target. 30 to 50 is difficult, college-level. Above 80 is conversational and very easy. Below 30 will lose almost any general audience. **Why six formulas instead of just Flesch-Kincaid?** Each weights sentence length against word complexity differently, so any single one can be skewed by a quirk of the text - a few long lists, one enormous sentence. You get all six raw scores plus their consensus, so you can gate on the stable number and still inspect the outliers. **How do I check the reading level of a whole website?** Extract the page text first (a page-text extractor pairs well), then batch up to 100 texts per run here and sort by `consensusGrade`. At $0.0004 per page a 1,000-page audit is $0.40. **What do the suggestions look like?** Mechanical and specific, with your measured numbers in them: "Sentences average 27 words - break long sentences into shorter ones (target <20). 55.6% of words have 3+ syllables - swap in simpler synonyms." **Does it work on non-English text?** No - see "When NOT to use this". It will return numbers, and those numbers will not mean anything. **Why did some rows come back `ok: false`?** The input contained no words, only punctuation or symbols. Recorded with the reason, never charged. ### Use from code or AI agents ```bash curl -s "https://api.apify.com/v2/acts/EliAI~text-readability-analyzer/run-sync-get-dataset-items?token=$APIFY_TOKEN" \ -X POST -H 'Content-Type: application/json' \ -d '{"text": "Your draft goes here."}' ``` Agents: connect [Apify MCP](https://mcp.apify.com) and call the `EliAI/text-readability-analyzer` tool. - **Capability:** score one or many texts across 6 readability formulas with consensus grade, audience label and fix-it tips - **Required input:** `text` (string) or `texts` (array) - **Returns:** one record per text; `consensusGrade` and `suggestion` are the headline fields - **Bounded:** 100 texts per run; failures isolate per text - **Side effects:** none (texts never leave the run) ### Related actors - **Text Statistics** (`EliAI/text-statistics`) - the counts alone, without the formulas. - **Language Detector** (`EliAI/text-language-detector`) - run this first to keep non-English text out of your readability audit. # Actor input Schema ## `text` (type: `string`): A single block of text to score for readability (Flesch, Gunning Fog, SMOG, ARI, and more). ## `texts` (type: `array`): List of text blocks to analyze in one run. Each is scored independently. When this list is filled, the single text above is ignored, so you are only charged for the texts you listed. ## `maxTexts` (type: `integer`): Hard cap on how many texts to process per run (1-100). ## Actor input object example ```json { "text": "The quick brown fox jumps over the lazy dog. Readability matters: clear, concise writing reaches more people. Long, convoluted sentences crammed with multisyllabic terminology inevitably diminish comprehension among general audiences.", "texts": [], "maxTexts": 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "text": "The quick brown fox jumps over the lazy dog. Readability matters: clear, concise writing reaches more people. Long, convoluted sentences crammed with multisyllabic terminology inevitably diminish comprehension among general audiences." }; // Run the Actor and wait for it to finish const run = await client.actor("eliai/text-readability-analyzer").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "text": "The quick brown fox jumps over the lazy dog. Readability matters: clear, concise writing reaches more people. Long, convoluted sentences crammed with multisyllabic terminology inevitably diminish comprehension among general audiences." } # Run the Actor and wait for it to finish run = client.actor("eliai/text-readability-analyzer").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 '{ "text": "The quick brown fox jumps over the lazy dog. Readability matters: clear, concise writing reaches more people. Long, convoluted sentences crammed with multisyllabic terminology inevitably diminish comprehension among general audiences." }' | apify call eliai/text-readability-analyzer --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,eliai/text-readability-analyzer" } } } ``` 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 ` 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/kb6Eax7XsVEARvhZ4/builds/KhSrzu7D3KiEx6Chd/openapi.json