How to filter news by read time and readability#

To match articles by length, add the read_time parameter (estimated reading time in minutes); to match by reading difficulty, add a readability.* parameter such as readability.ease. For example, read_time.max=4 keeps only short articles, and is_easy_read=1 keeps only articles that are easy to read.

curl "https://api.apitube.io/v1/news/everything?read_time.max=4&is_easy_read=1&api_key=YOUR_API_KEY"

You can send the key as a header (X-API-Key: YOUR_API_KEY) instead of the api_key query parameter. Both the read-time and readability filters are part of the shared filter chain, so they work together with every other filter in a single request.

How to filter news by reading time#

read_time matches articles by their estimated reading time in minutes. Use the exact form read_time, or bound a range with read_time.min and read_time.max:

curl "https://api.apitube.io/v1/news/everything?read_time.min=2&read_time.max=6&api_key=YOUR_API_KEY"

The request above returns articles that take between 2 and 6 minutes to read. There are also five convenience flags so you don’t have to remember the cut-offs — each maps to a fixed range in minutes:

• is_quick_read=1 — read time of 2 minutes or less
• is_short_read=1 — read time under 3 minutes
• is_medium_read=1 — read time of 3 to 7 minutes
• is_long_read=1 — read time of 5 minutes or more
• is_deep_dive=1 — read time of 10 minutes or more

Each flag accepts 0 or 1; passing a value of 1 applies the filter. Every article in the response carries a top-level read_time field (in minutes), so you can confirm the length of each result.

How to filter news by readability score#

The readability.* family filters articles by how hard the text is to read, using three standard metrics. Each metric supports an exact match plus a .min / .max range:

• readability.ease — Flesch Reading Ease, a 0–100 score where higher means easier. readability.ease.min=60 keeps plain-language articles.
• readability.fk_grade — Flesch-Kincaid Grade Level, 0–30, where the value is roughly the US school grade needed to follow the text. Lower is easier.
• readability.ari — Automated Readability Index, 0–30, another grade-level estimate.

curl "https://api.apitube.io/v1/news/everything?readability.ease.min=60&readability.fk_grade.max=10&api_key=YOUR_API_KEY"

For the two convenience shortcuts based on Flesch Reading Ease, is_easy_read=1 keeps articles scoring 60 or above, and is_difficult_read=1 keeps articles scoring below 40. Each result includes a readability object with flesch_reading_ease, flesch_kincaid_grade and automated_readability_index, so you can see the exact scores behind the filter.

How to filter by difficulty level, audience and reading age#

Two categorical parameters group articles without you having to pick a numeric cut-off. readability.difficulty accepts beginner, intermediate, advanced or expert (case-insensitive). readability.audience accepts children, general, professional or academic:

curl "https://api.apitube.io/v1/news/everything?readability.audience=general&readability.difficulty=intermediate&api_key=YOUR_API_KEY"

You can also target a recommended reader age with readability.age, or a range with readability.age.min and readability.age.max, accepting values from 6 to 22. The response readability object exposes the matching difficulty_level, target_audience and reading_age for each article.

How to sort and combine read time with other filters#

read_time is also a valid sort key. This request returns easy-to-read general-audience articles, shortest first:

curl "https://api.apitube.io/v1/news/everything?is_easy_read=1&readability.audience=general&sort.by=read_time&sort.order=asc&api_key=YOUR_API_KEY"

Because these filters share the chain with language, date, source and bias filters, you can stack them freely. To narrow the language of the results, see How to filter news by language; to bias the source lean, see How to filter news by source political bias. Full definitions live in the official News API parameters reference.

Which endpoints support read time and readability?#

Both filter families run in the shared filter chain, so they work on /v1/news/everything, /v1/news/top-headlines and /v1/news/entity, on both GET (query string) and POST (request body) requests.

Common Questions#

• What unit is read_time measured in?
• What is the difference between readability.ease and readability.fk_grade?
• What happens if I pass an invalid value?
• Can I combine read time and readability in one request?

What unit is read_time measured in?#

read_time, read_time.min and read_time.max are all measured in minutes, and so are the convenience flags. For example, is_deep_dive=1 matches articles with a read time of 10 minutes or more.

What is the difference between readability.ease and readability.fk_grade?#

readability.ease is the Flesch Reading Ease score on a 0–100 scale where higher values are easier to read. readability.fk_grade is the Flesch-Kincaid Grade Level, where a lower value means easier text. They measure the same underlying difficulty from opposite directions, so a high readability.ease value usually corresponds to a low readability.fk_grade value.

What happens if I pass an invalid value?#

Unlike some filters that silently ignore bad input, the read-time and readability filters validate their values. A non-numeric read_time, or a readability.difficulty outside beginner, intermediate, advanced and expert, returns an HTTP 400 error with a specific code (for example ER0187 for an invalid read_time) rather than running the search. Check the value before retrying.

Can I combine read time and readability in one request?#

Yes. Read-time and readability parameters run in the same filter chain, so you can apply several at once — for instance read_time.max=6 together with is_easy_read=1 — to return short, plain-language articles in a single call.