---
url: 'https://docs.apitube.io/platform/news-api/top-headlines.md'
description: >-
  Get breaking and important news from highly ranked sources with
  /v1/news/top-headlines. Find endpoint details, request examples, limits and
  errors.
---

# Get top headlines with `/v1/news/top-headlines`

Use `/v1/news/top-headlines` for news from publishers with an Open Page Rank of 5 or above. It supports the shared [Filters](/platform/news-api/filters), counts by field, highlighting and exports. The source-rank requirement always applies.

Each request costs **1 point**. Using the `prompt` parameter adds **2 points** for the translation step; `prompt` requires Basic or above.

## Endpoint

```
GET  /v1/news/top-headlines
POST /v1/news/top-headlines
```

Base URL: `https://api.apitube.io`. GET and POST return the same results. Put filters in the URL with `GET` or send them as JSON in the request body with `POST`.

## How top headlines differ from a search

| | `/v1/news/top-headlines` | `/v1/news/everything` |
|---|---|---|
| Source pool | High-authority sources only (`source.rank.opr` ≥ 5) | Every indexed source |
| Typical use | A front page, a breaking-news feed | Full-archive research, monitoring, exports |
| Filters | Identical | Identical |

To choose your own minimum source rank, use `/v1/news/everything` with `source.rank.opr.min`.

## Parameters

See [Filters](/platform/news-api/filters) for all shared search filters, sorting, pagination, field selection and other request options.

## Response format

The response uses the shared [Response format](/platform/news-api/response-structure). Read articles from `results` and original article links from `href`. See [API Response Structure](/platform/news-api/response-structure#article-object-fields) for all fields.

## Request examples

### GET with query filters

::: code-group

```bash [cURL]
curl "https://api.apitube.io/v1/news/top-headlines?language.code=en&source.country.code=us&per_page=10&api_key=YOUR_API_KEY"
```

```python [Python]
import requests

response = requests.get(
    "https://api.apitube.io/v1/news/top-headlines",
    params={"language.code": "en", "source.country.code": "us", "per_page": 10},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

for article in response.json()["results"]:
    print(article["source"]["domain"], article["title"])
```

```javascript [Node.js]
const params = new URLSearchParams({
  'language.code': 'en',
  'source.country.code': 'us',
  per_page: '10'
});

const response = await fetch(`https://api.apitube.io/v1/news/top-headlines?${params}`, {
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
});
const data = await response.json();

console.log(data.results.map(a => a.title));
```

```php [PHP]
$query = http_build_query([
    'language.code' => 'en',
    'source.country.code' => 'us',
    'per_page' => 10,
    'api_key' => 'YOUR_API_KEY',
]);

$data = json_decode(file_get_contents("https://api.apitube.io/v1/news/top-headlines?$query"), true);

print_r(array_column($data['results'], 'title'));
```

:::

### Headlines for one category

```bash
curl "https://api.apitube.io/v1/news/top-headlines?category.id=medtop:04000000&language.code=en&api_key=YOUR_API_KEY"
```

Category IDs come from [List of Categories](/platform/news-api/list-of-categories) or from [`/v1/suggest/categories`](/platform/news-api/suggest/categories).

## Limits

The same limits as `/v1/news/everything` apply: results per page, accessible pages and the 31-day title-search window. See [Rate limits and quotas](/platform/news-api/rate-limits).

## Errors

Same codes as [`/v1/news/everything`](/platform/news-api/everything#errors), documented in full in [HTTP response codes](/platform/news-api/http-response-codes).

## Related

* [Search articles](/platform/news-api/everything) — the same filters over every source.
* [Local news](/platform/news-api/local) — headlines around a point on the map.
* [Parameters reference](/platform/news-api/filters#parameters) — syntax and examples for every filter family.