APITube Help Center

How to Get Top Headlines from the News API

Use /v1/news/top-headlines to fetch important news from high-authority sources

Kent Hudson

Written by Kent Hudson

June 26, 2026

Open this example in the API Playground ↗

How to get top headlines

To get the most important news from high-authority sources, call the /v1/news/top-headlines endpoint. It returns the same article objects as the main search, but pre-filtered down to stories flagged as important and published by sources with an Open Page Rank (OPR) of at least 5. By default the results come back newest-first. This fetches the current English top headlines:

curl "https://api.apitube.io/v1/news/top-headlines?language.code=en&api_key=YOUR_API_KEY"

You can pass your key as the api_key query parameter or as an X-API-Key header.

What makes an article a top headline?

/v1/news/top-headlines applies two built-in conditions that the regular search does not:

  • The article is flagged as important (a breaking or high-significance story).
  • The source has an OPR score of 5 or higher — OPR (Open Page Rank) measures a publisher’s authority, so this keeps low-authority sites out.

Everything that matches both conditions is eligible; everything else is excluded before your own filters even run. That is the entire difference between top-headlines and a normal search — it is a curated, high-authority slice of the same catalogue.

Apart from those two conditions, /v1/news/top-headlines accepts exactly the same parameters as /v1/news/everything: the full filter set, sorting, pagination, faceting, highlighting and export formats all work identically. Anything you can do on the main search, you can do here on top of the high-authority pre-filter.

That means you can take a query you already use for search, swap the path to /v1/news/top-headlines, and get the same query restricted to important, authoritative stories. For the complete list of filters you can combine, see the Searching & Filtering News section.

How to narrow top headlines by language, country or category

Add filters as query parameters (GET) or as a JSON body (POST). For example, to get the most relevant business top headlines using an IPTC category code, sorted by relevance:

curl "https://api.apitube.io/v1/news/top-headlines?category.id=medtop:13000000&sort.by=relevance&sort.order=desc&api_key=YOUR_API_KEY"

A few common filters you can layer on:

  • language.code=en — limit to a language (2-letter code).
  • source.domain=bbc.com — limit to a specific publisher’s domain.
  • published_at.start=2026-06-01 — only headlines on or after a date.
  • category.id=medtop:13000000 — a single IPTC category. See How to filter news by category.

How are top headlines sorted, and can I change it?

By default, results are sorted by published_at in descending order — newest headlines first. Override it with sort.by and sort.order. Supported sort modes include relevance, engagement, quality, controversy, trust and published_at. For example, sort.by=engagement&sort.order=desc surfaces the headlines getting the most social traction first.

What does the top-headlines response look like?

The response has the same shape as a normal search response, plus one field unique to this endpoint: a headlines array containing just the titles, alongside the full results array.

{
  "status": "ok",
  "limit": 100,
  "page": 1,
  "has_next_pages": true,
  "request_id": "9f2c1e7a-4b3d-4c8e-a1f0-2d6b8c4e7a11",
  "headlines": [
    "Central bank holds rates steady amid inflation concerns",
    "Major automaker recalls 200,000 vehicles over a brake fault"
  ],
  "results": [
    {
      "id": 123456789,
      "href": "https://example.com/markets/central-bank-holds-rates",
      "published_at": "2026-06-26T09:15:00Z",
      "title": "Central bank holds rates steady amid inflation concerns",
      "language": "en",
      "source": {
        "id": 4232,
        "domain": "example.com",
        "rankings": { "opr": 7 }
      }
    }
  ]
}

The headlines array is handy when you only want to render a list of titles. Each object in results carries the usual article fields — id, href, published_at, title, description, body, language, source, categories, entities, sentiment and the rest — the same shape returned by the search endpoints (see the API response structure).

How much does a top-headlines request cost?

Each call that returns results costs 1 point, the same as a search request — regardless of how many headlines come back. If the query matches nothing, no point is spent. You can page through results with page and per_page (default 100, maximum 250); requesting more than 250 returns error ER0171.

Common Questions

Can I call top-headlines with POST?

Yes. /v1/news/top-headlines accepts both GET and POST. With GET, send filters as query parameters; with POST, send them as a JSON body with Content-Type: application/json. Both run the same query and return the same response.

Because top-headlines always applies its two built-in conditions — important article and source OPR ≥ 5 — on top of your filters. A query that returns thousands of articles on /v1/news/everything will return far fewer here, since most articles either are not flagged important or come from lower-authority sources. If you need everything matching your filters, use the search endpoints instead. If you only need a count, see How to count matching articles without downloading them.

Why is the article content truncated?

If you are using a test key or are on the free plan, article content is truncated (a preview, with an upgrade marker in place of the full body). This applies to top-headlines just like any other endpoint. Switch to a live key on a paid plan to receive full article bodies.

What errors can top-headlines return?

The errors mirror the rest of the API: ER0201/ER0202 (HTTP 401) when the API key is missing or invalid, ER0176 (HTTP 402) when your account has no points left, and ER0203 (HTTP 429) when you exceed the rate limit (50 requests per minute on paid plans, 10 on the free plan; repeated violations lead to a temporary ban). Each response includes a request_id to help you trace the call.

Related Articles