How to sort news by controversy, trust and social shares#

To rank results by something other than date, set sort.by to one of the composite scores — engagement, controversy or trust — or to a social-share key such as shares.facebook.max. By default the News API sorts by published_at in descending order, so newest first; the moment you pass a different sort.by, results are ranked by that signal instead.

curl "https://api.apitube.io/v1/news/everything?sort.by=controversy&category.id=medtop:11000000&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. Composite scores are returned highest-first because the default sort.order is desc — you do not need to add sort.order to get the top-scoring articles at the top.

What are the composite sort modes?#

The News API ships three multifactor scores you can pass to sort.by. Each blends several article signals into a single number, so you pick the one that matches what “best” means for your use case:

• engagement — viral potential for social feeds. It rewards breaking/important articles, the number of images and videos, positive sentiment, and freshness (an article published within the last hour gets the biggest boost, within the last six hours a smaller one), plus the rank of the source.
• controversy — polarization, for debates and hot topics. It rewards strong sentiment in either direction (intensity, not just positive), articles from left- or right-leaning sources (anything other than center), video content, and breaking news.
• trust — credibility, for fact-checking and research. It rewards a high source rank, articles that are not duplicates, articles that are not paywalled, neutral sentiment, and articles that carry a named author.

There are two more composite modes, relevance and quality, but the three above are the ones that change ranking by social and editorial signals.

How to sort by engagement, controversy or trust#

Pass the mode name as sort.by. This returns the most trustworthy articles about a company first:

curl "https://api.apitube.io/v1/news/everything?title=Tesla&sort.by=trust&api_key=YOUR_API_KEY"

Because the three modes weight signals differently, the same query reordered by engagement versus controversy versus trust can surface very different articles. A practical pattern is a “what’s blowing up right now” feed — recent breaking coverage ranked by viral potential:

curl "https://api.apitube.io/v1/news/everything?is_breaking=1&sort.by=engagement&api_key=YOUR_API_KEY"

How to sort by social shares#

To rank by how widely an article was shared, use a share key: shares.facebook.max, shares.twitter.max or shares.reddit.max. Each maps to that platform’s share count, and with the default sort.order=desc the most-shared articles come first:

curl "https://api.apitube.io/v1/news/everything?title=climate&sort.by=shares.twitter.max&sort.order=desc&api_key=YOUR_API_KEY"

Keep one timing detail in mind: share counts are aggregated gradually over roughly two hours after an article is published. A story that went live a few minutes ago will show low share numbers that climb until they settle, so very fresh articles can rank lower than their eventual reach.

How to sort by total media content#

media_richness ranks articles by the total amount of media they carry — the image count plus the video count. It is the right choice for a visual feed where richer articles should win:

curl "https://api.apitube.io/v1/news/everything?has_image=1&sort.by=media_richness&api_key=YOUR_API_KEY"

For richer control over which images qualify before you sort, combine this with the media-quality filters described in How to filter by media quality and social-ready images.

How to flip the sort direction#

sort.order takes two values, asc and desc, and defaults to desc. Add sort.order=asc when you want the lowest scores first — for example, the least controversial coverage of a topic:

curl "https://api.apitube.io/v1/news/everything?category.id=medtop:11000000&sort.by=controversy&sort.order=asc&api_key=YOUR_API_KEY"

A common pairing for trust-led research is to keep only non-duplicate, non-paywalled articles and then rank what is left by credibility — see How to exclude paywalled or duplicate articles for those filters. All sort options are listed in the official News API parameters reference.

Which endpoints support these sort modes?#

Sorting works on the search and retrieval endpoints that return article lists: /v1/news/everything, /v1/news/top-headlines, /v1/news/category, /v1/news/topic, /v1/news/industry and /v1/news/entity. Each accepts sort.by and sort.order on both GET (query string) and POST (request body).

Common Questions#

• What is the default sort order?
• What happens if I pass an unknown sort.by value?
• Why do brand-new articles rank low when sorting by shares?
• What is the difference between engagement and controversy?

What is the default sort order?#

If you do not pass sort.by, results are sorted by published_at (publication date), and the default sort.order is desc, so the newest articles come first. Every composite and share mode also defaults to desc, which means the highest score appears first unless you set sort.order=asc.

What happens if I pass an unknown sort.by value?#

An unrecognized sort.by value does not raise an error — the request quietly falls back to sorting by published_at. So a typo such as sort.by=trustt will silently return date-sorted results instead of trust-ranked ones. Check the value against the supported list if a sort does not behave the way you expect.

Why do brand-new articles rank low when sorting by shares?#

Social share counts are not final at publication. They are aggregated over roughly two hours after the article goes live, so a just-published story shows low Facebook, Twitter or Reddit numbers that rise over time. When you sort by shares.*, very recent articles can appear below older ones simply because their share totals have not caught up yet.

What is the difference between engagement and controversy?#

Both reward breaking news and video, but they treat sentiment and sources differently. engagement boosts positive sentiment, fresh timing and high-rank sources to predict viral reach. controversy boosts sentiment intensity in either direction and left- or right-leaning (non-center) sources to surface polarizing, debate-worthy coverage — so a calm, widely-shared article scores well on engagement but not on controversy.