A readability score turns a page into a school grade. That sounds reductive, and it is, which is exactly why the number is useful as a check and harmful as a target.
The Readability metrics API returns the score together with the statistics behind it: words, sentences, syllables and three averages. Read the statistics first, then the grade.
curl -s "https://api2.globus.studio/v2/readability-check?text=Your%20text%20here&lang=en"What the readability score measures
Every formula counts two things: words per sentence and syllables per word. Long sentences and long words raise the grade; short ones lower it. The score says nothing about whether the text is true, useful or well organised.
A grade of 9 means a reader with nine years of schooling can follow the sentences. It is a rough mapping, not a measurement of intelligence, and it was built for English. Other languages get their own coefficients, and some formulas are dropped where the language has no support: those fields come back as null.
Read the statistics before the grade
avg_words_per_sentence above 25 is a reliable sign of a paragraph that needs splitting. That one number catches most of what a readability score complains about, and fixing it usually raises the grade without rewriting the vocabulary.
avg_syllables_per_word above 2 marks a dense vocabulary. Sometimes the vocabulary is the point: a legal notice needs precise terms, and replacing them with short synonyms creates a different problem.
reading_time_minutes is worth showing to the reader. It comes from the same word count, and “4 min read” is honest in a way a grade is not.
Compare pages, not languages
A readability score is only comparable inside one language and one formula. Flesch counts English syllables; applied to German compounds it produces a number that looks plausible and means nothing. Pass the right lang, and compare a Russian page with another Russian page.
The same rule applies across formulas. Flesch Reading Ease runs from 0 to 100 where higher is easier. Gunning Fog reports a grade where lower is easier. Mixing them in one dashboard creates a chart that reads as noise.
Set a range, not a target
Pick a band per content type and leave it there. Developer documentation tends to sit at grade 10 to 12. Marketing pages for a general audience sit lower. Legal text sits higher and should stay there.
A team that chases “grade 8” everywhere will cut necessary words from a reference page and add filler to a short one. A band is a flag: text that leaves the band gets a second read, and a person decides whether the change is right.
Where a readability score misleads
Short samples swing hard. A paragraph of three sentences can move ten grades between runs. Score a full page, not a snippet.
Lists, tables and code blocks confuse the sentence counter. A page that is mostly code will read as easy or nonsensical depending on the formula, so exclude code-heavy pages from the band or accept that the number is rough.
Proper nouns and product names count as long words. A page full of API names looks harder than it reads, and the fix is not to rename the product.
Put a readability score in the publishing checklist
Run the check before publishing, store the result next to the page, and compare revisions of the same page. A jump of five grades between two drafts usually means a section was pasted in from somewhere else, which is the kind of change worth noticing.
The endpoint accepts text or a public URL, up to 2 MB, and gives up after a few seconds. For a page behind a login, fetch the text yourself and send it in the body instead.
Keep a log of the scores
One grade on one page says little. A log with the page, the date, the editor and the average words per sentence shows a slow drift that no single review would notice. When a page leaves its band twice in a row, read it; when it leaves once, ignore it. The log also makes the band itself negotiable: after a month it is obvious whether the range fits the content or was copied from a blog post about readability.
Related reading
To confirm the language before you trust the numbers, use text language detection. For filler text of a fixed length while a layout is built, see the placeholder text guide.
Further reading: WCAG 2.1 on reading level.