curl --request POST \
  --url https://api.newscatcherapi.com/news-api/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "q": "What is happening with the Florida hurricane recovery?",
  "effort": "medium",
  "limit": 20
}
'

{
  "query": "hurricane recovery florida",
  "effort": "medium",
  "took_ms": 3664,
  "window": {
    "search_window": "7d",
    "hours": 168,
    "from": "2026-10-21T14:12:35.408254+00:00",
    "to": "2026-10-28T14:12:35.408254+00:00"
  },
  "count": 1,
  "results": [
    {
      "id": "876a97d2bc58f3c2437ad7b03a06ebfe",
      "title": "Major disaster declared in Florida following Hurricane Isaias; federal aid approved",
      "language": "en",
      "url": "https://www.fox10tv.com/2026/10/28/major-disaster-declared-florida-following-hurricane-isaias-federal-aid-approved",
      "source": {
        "domain": "fox10tv.com",
        "name": "FOX10News"
      },
      "published_at": "2026-10-28T01:05:37+00:00",
      "crawled_at": "2026-10-28T01:06:57+00:00",
      "content_type": "news_report",
      "story": {
        "id": "6f1c2b0e-2f0f-4d52-9a0b-5d0e8a5f9d11",
        "newsrooms": 40
      },
      "score": 36.1871,
      "country": "US",
      "snippet": "President Donald J. Trump approved a Major Disaster Declaration for Florida on Tuesday, releasing federal funding to assist with recovery…",
      "summary": "Trump approved a major disaster declaration for Florida after Hurricane Isaias, unlocking federal recovery funds."
    }
  ]
}

Search news (JSON body)

Ranked real-news articles for a request in plain words or with keywords, grouped into stories.

How it ranks. Every article is scored on relevance to the request, the authority of its publisher, how many newsrooms cover its story and how fresh it is. effort decides how much further work goes into the order: low stops there, medium adds a cross-encoder rerank of the top stories, high adds an LLM judgement of them and merges stories that report the same event. Articles in every language are searched through their English translation, unless every language you ask for is not English (then the original language is searched).

Filters. languages, countries, sources and min_newsrooms narrow the search, not_languages, not_countries and not_sources leave articles out; search_window sets how far back to search, on the publication date (on the crawl date with sort_by=crawled_at): a number and a unit such as 15m, 2h, 1d, 15 minutes, 2 hours or 1 day (7 days by default, up to your plan’s history). collapse decides what happens to several articles of one story. sort_by is relevancy (default), published_at or crawled_at (newest first; it covers the best matches of q, not every article of the window). An upper-case NOT in q drops the articles that mention the term in their headline, description or summary.

Credits. A successful search (200) costs 1, 5 or 10 NCC for low, medium or high effort, also when it finds nothing. A refused or failed request is not charged. Your balance and limits are in GET /subscription.

Two ways to call it. GET /search with the parameters in the query string, or POST /search with the same parameters as a JSON body. In both, sources, languages, countries, their not_ versions and include take a comma-separated string; in the JSON body they can also be arrays.

POST

curl --request POST \
  --url https://api.newscatcherapi.com/news-api/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "q": "What is happening with the Florida hurricane recovery?",
  "effort": "medium",
  "limit": 20
}
'

{
  "query": "hurricane recovery florida",
  "effort": "medium",
  "took_ms": 3664,
  "window": {
    "search_window": "7d",
    "hours": 168,
    "from": "2026-10-21T14:12:35.408254+00:00",
    "to": "2026-10-28T14:12:35.408254+00:00"
  },
  "count": 1,
  "results": [
    {
      "id": "876a97d2bc58f3c2437ad7b03a06ebfe",
      "title": "Major disaster declared in Florida following Hurricane Isaias; federal aid approved",
      "language": "en",
      "url": "https://www.fox10tv.com/2026/10/28/major-disaster-declared-florida-following-hurricane-isaias-federal-aid-approved",
      "source": {
        "domain": "fox10tv.com",
        "name": "FOX10News"
      },
      "published_at": "2026-10-28T01:05:37+00:00",
      "crawled_at": "2026-10-28T01:06:57+00:00",
      "content_type": "news_report",
      "story": {
        "id": "6f1c2b0e-2f0f-4d52-9a0b-5d0e8a5f9d11",
        "newsrooms": 40
      },
      "score": 36.1871,
      "country": "US",
      "snippet": "President Donald J. Trump approved a Major Disaster Declaration for Florida on Tuesday, releasing federal funding to assist with recovery…",
      "summary": "Trump approved a major disaster declaration for Florida after Hurricane Isaias, unlocking federal recovery funds."
    }
  ]
}

Authorizations

x-api-key

string

header

required

Your NewsCatcher API key, created in the NewsCatcher platform. Send it in the x-api-key header of every request.

Body

application/json

What to search for and how. The same parameters are accepted in the query string of GET /search and in the JSON body of POST /search.

string

required

What to look for: keywords with AND/OR/NOT or a plain-language question, in any language. An upper-case NOT (Apple NOT iPhone, NOT "model y") drops the articles whose headline, description or summary mention the term.

Required string length: 1 - 500

Example:

"Tesla recall NOT Cybertruck"

effort

enum<string>

default:medium

How much work goes into the ranking, and the price: low ranks by relevance, authority, coverage and freshness (1 NCC); medium adds a cross-encoder rerank of the top stories (5 NCC); high adds an LLM rerank and merges stories about the same event (10 NCC). Charged only when the search succeeds.

Available options:

low,

medium,

high

Example:

"medium"

limit

integer

default:20

Number of articles to return (1 to 100; a plan may allow fewer, e.g. 50 on Free: the request is refused with 403 above it).

Required range: 1 <= x <= 100

Example:

20

collapse

enum<string>

default:diverse

diverse (default) discounts repeated articles of one story, story keeps one article per story, duplicates keeps every article (copies of one article are always one result).

Available options:

diverse,

story,

duplicates

Example:

"diverse"

sort_by

enum<string>

default:relevancy

The order of the results: relevancy (default) best match first; published_at newest publication first; crawled_at newest crawl first. A date order covers the best matches of q (at least 100, or 5 times limit), not every article of the window, and collapse=diverse then keeps every article, as duplicates does. A publication date later than the crawl date counts as the crawl date.

Available options:

relevancy,

published_at,

crawled_at

Example:

"relevancy"

search_window

string

How far back to search, counted from now and measured on the publication date: a number and a unit, for example 15m, 2h, 1d, 15 minutes, 2 hours, 1 day or 1w. From 1 minute up to your plan's history (30 days on the free plan; a longer request is cut to it and the response says window.clamped). Default: 7d.

Pattern: ^\s*\d+(\.\d+)?\s*[a-zA-Z]+\s*$

Examples:

"7d"

"2h"

"15m"

"1 day"

"2 hours"

"15 minutes"

sources

Only search these publishers: domains, comma-separated or as an array (at most 100). Matches any copy of an article. The result then shows the requested domain: its name, and a link of that domain (with several matching domains on one article, the first of them in the article's order).

Example:

"reuters.com,bbc.co.uk"

languages

Only articles in these languages: ISO 639-1 codes, comma-separated or as an array (at most 100). zh is searched as cn.

Example:

"en,de"

countries

Only articles from publishers in these countries: ISO 3166-1 alpha-2 codes, comma-separated or as an array (at most 100).

Example:

"US,GB"

not_sources

Leave out these publishers: domains, comma-separated or as an array (at most 100). An article is dropped when any of its copies comes from one of them.

Example:

"reuters.com,bbc.co.uk"

not_languages

Leave out articles in these languages: ISO 639-1 codes, comma-separated or as an array (at most 100). zh is excluded as cn.

Example:

"en,de"

not_countries

Leave out articles from publishers in these countries: ISO 3166-1 alpha-2 codes, comma-separated or as an array (at most 100).

Example:

"US,GB"

min_newsrooms

integer

default:0

Only stories carried by at least this many newsrooms.

Required range: 0 <= x <= 1000

Example:

3

content_type

enum<string>

default:news

news (default) keeps real news articles only; all returns every article, whatever its type.

Available options:

news,

all

Example:

"news"

include

Heavy fields to add to every result, comma-separated or as an array: description, entities, sentiment, themes, translation, embedding. Enterprise accounts only (403 enterprise_field otherwise).

Example:

"entities,sentiment"

Response

The articles, best first. count is 0 and results empty when nothing matched.

The articles that match a search, with the window that was searched.

query

string

required

The query as received (control characters replaced, ends trimmed).

Example:

"hurricane recovery florida"

effort

enum<string>

required

The effort level that ran: low, medium or high.

Available options:

low,

medium,

high

Example:

"medium"

took_ms

integer

required

Time the search took on our side, in milliseconds.

Required range: x >= 0

Example:

3664

window

NewsWindow · object

required

The time window that was searched: search_window back from to, which is when the search ran.

Show child attributes

count

integer

required

Number of results returned (at most limit).

Required range: x >= 0

Example:

1

results

NewsResult · object[]

required

The articles, in the order of sort_by.

Show child attributes

sort_by

string | null

The order of the results: relevancy (best match first), published_at or crawled_at (newest first).

Example:

"relevancy"

excluded

string[] | null

The terms of the NOT clauses of q: articles whose headline, description or summary mention one are left out. Absent when q has no NOT.

Example:

["iPhone"]

News API

Agent

Search news (JSON body)

Authorizations

Body

Response