API reference overview

Base URL

https://v3-api.newscatcherapi.com/api

Append the endpoint path to this base URL for every request. There is no sandbox environment — all requests run against production.

Authentication

Pass your API key in the x-api-token header on every request:

x-api-token: YOUR_API_KEY

For implementation examples in all supported languages, see Authentication.

Request format

All endpoints support both GET and POST. When using POST, set Content-Type: application/json and pass parameters in the JSON request body.

curl -X POST "https://v3-api.newscatcherapi.com/api/search" \
  -H "x-api-token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "renewable energy",
    "lang": "en",
    "page_size": 1
  }'

from newscatcher import NewscatcherApi

client = NewscatcherApi(api_key="YOUR_API_KEY")

response = client.search.post(
    q="renewable energy",
    lang="en",
    page_size=1,
)

print(response.articles[0].title)

import { NewscatcherApiClient } from "newscatcher-sdk";

const client = new NewscatcherApiClient({ apiKey: "YOUR_API_KEY" });

const response = await client.search.post({
  q: "renewable energy",
  lang: "en",
  pageSize: 1,
});

console.log(response.articles?.[0]?.title);

import com.newscatcher.api.NewscatcherApiClient;
import com.newscatcher.api.resources.search.requests.PostSearchRequest;

NewscatcherApiClient client = NewscatcherApiClient.builder()
    .apiKey("YOUR_API_KEY")
    .build();

var response = client.search().post(
    PostSearchRequest.builder()
        .q("renewable energy")
        .lang("en")
        .pageSize(1)
        .build()
);

System.out.println(response.getArticles().get(0).getTitle());

	GET	POST
Parameters	URL query string	JSON request body
URL length limit	Limited (varies by client)	None
Best for	Quick testing and debugging	Complex filters, production integrations

For most production integrations, POST is the better choice — it avoids URL length limits and keeps parameters out of server logs and browser history.

Response format

All endpoints return JSON with the following top-level envelope:

{
  "status": "ok",
  "total_hits": 10000,
  "page": 1,
  "total_pages": 100,
  "page_size": 100,
  "articles": [],
  "user_input": {}
}

The articles array contains the matched article objects. The full schema is available in each endpoint reference. The response also includes a user_input object that echoes the specified parameters and defaults as interpreted by the API — useful for debugging unexpected results.

Pagination

Two parameters control pagination:

Parameter	Default	Maximum
`page`	`1`	No hard limit, but results cap at 10,000 articles per request
`page_size`	`100`	`1000`

A query can return at most 10,000 articles per request. If total_hits is 10000, the actual match count is likely higher. To learn how to retrieve beyond this limit, see Retrieve large datasets.

Rate limits

Rate limits vary by subscription plan. Exceeding your limit returns a 429 status code. For plan-specific limits and retry guidance, see Rate limits.

Errors

All error responses use a consistent JSON envelope:

{
  "message": "Invalid api key",
  "status_code": 401,
  "status": "Unauthorized"
}

For the full list of status codes and resolution steps, see Errors.

Endpoints

News API provides the following endpoints. All endpoints support both GET and POST methods.

Endpoint	Description
/search	Searches for articles by keyword, phrase, or Boolean query. Supports filtering by language, country, source, date range, sentiment, NLP tags, and more.
/latest_headlines	Returns the most recent headlines published within a specified time window. Supports filtering by language, country, source, and NLP attributes.
/breaking_news	Returns actively breaking news events, each with a configurable number of top representative articles. Supports filtering by NLP theme, sentiment, and source rank.
/authors	Searches for articles written by a specified author or set of authors. Supports the same filtering options as article search.
/search_by_link	Retrieves articles by their URL or NewsCatcher article ID. Use this endpoint to look up specific articles when you already know their links or identifiers.
/sources	Returns a list of news sources indexed by NewsCatcher. Supports filtering by language, country, domain type, news category, and SEO rank.
/aggregation_count	Returns article counts aggregated by day, hour, or month for a given query. Use this endpoint to analyze publication volume trends over time.
/subscription	Returns details about your current subscription plan, including usage limits and entitlements.

Get started

Guides and concepts

How to

Troubleshooting

API Reference

Libraries

API reference overview

Base URL

Authentication

Request format

Response format

Rate limits

Errors

Endpoints

​Base URL

​Authentication

​Request format

​Response format

​Pagination

​Rate limits

​Errors

​Endpoints

Base URL

Authentication

Request format

Response format

Pagination

Rate limits

Errors

Endpoints