---
name: orthogonal-newscatcher-news-api
description: "Call NewsCatcher News API through Orthogonal's pay-per-use Run API: Ranked, story-aware search of global news in every language: find articles by plain-language request or keywords, page through every article matching a boolean query over the last year, and read every article of one story."
---

# NewsCatcher News API — Orthogonal API

> Pay-per-use API on Orthogonal. Each call is billed to your Orthogonal balance.
> Base API: `https://api.orthogonal.com/v1/run` · [llms.txt](https://www.orthogonal.com/llms.txt) · [browse all APIs](https://www.orthogonal.com/catalog)

Ranked, story-aware search of global news in every language: find articles by plain-language request or keywords, page through every article matching a boolean query over the last year, and read every article of one story.

**Verified:** no

## Access

**Run API:** `POST https://api.orthogonal.com/v1/run`
**Auth:** `Authorization: Bearer $ORTHOGONAL_API_KEY`
Get an API key at https://www.orthogonal.com/account/keys

No account or key yet? Set up Orthogonal first with https://www.orthogonal.com/skill.md: it covers the CLI, the MCP server, the TypeScript SDK and sign-up, including an agent sign-up without a password (https://www.orthogonal.com/agent-signup.md).

Every call goes through the unified Run API: send the API `slug`, the endpoint `path`, and the `query`/`body` parameters. The response is `{ "success": true, "priceCents": <US cents>, "requestId": "...", "data": { ... } }`.

Quote first, free: the same request with `"dryRun": true` returns the price without calling the API or charging anything. On a retry after a timeout, send the same `Idempotency-Key` header so the call runs and bills once.

## Endpoints

### News search

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

See [Effort levels](/news/effort-levels), [Filters and sorting](/news/filters), [Writing queries](/news/writing-queries) and [Credits and pricing](/get-started/credits-and-pricing).

`GET /search`

**Estimated cost:** from $0.00109 per call (required params only), up to $0.0109; use `"dryRun": true` in the Run API request to check the exact cost before calling.

**Page:** https://www.orthogonal.com/api/newscatcher-news-api/083506f4-fa76-48b1-8dab-96f31487b607

**Docs:** https://www.newscatcherapi.com/docs/api-reference/search/search-news

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `q` | string | Yes | 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. |
| `effort` | string | No | 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. |
| `limit` | integer | No | 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). |
| `collapse` | string | No | `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). |
| `sort_by` | string | No | 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. |
| `search_window` | string | No | 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`. |
| `sources` | string | No | 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). |
| `languages` | string | No | Only articles in these languages: ISO 639-1 codes, comma-separated or as an array (at most 100). `zh` is searched as `cn`. |
| `countries` | string | No | Only articles from publishers in these countries: ISO 3166-1 alpha-2 codes, comma-separated or as an array (at most 100). |
| `not_sources` | string | No | 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. |
| `not_languages` | string | No | Leave out articles in these languages: ISO 639-1 codes, comma-separated or as an array (at most 100). `zh` is excluded as `cn`. |
| `not_countries` | string | No | Leave out articles from publishers in these countries: ISO 3166-1 alpha-2 codes, comma-separated or as an array (at most 100). |
| `min_newsrooms` | integer | No | Only stories carried by at least this many newsrooms. |
| `content_type` | string | No | `news` (default) keeps real news articles only; `all` returns every article, whatever its type. |
| `include` | string | No | 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). |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"newscatcher-news-api","path":"/search","method":"GET","query":{"q":"<string>","effort":"<string>","limit":"<integer>","collapse":"<string>","sort_by":"<string>","search_window":"<string>","sources":"<string>","languages":"<string>","countries":"<string>","not_sources":"<string>","not_languages":"<string>","not_countries":"<string>","min_newsrooms":"<integer>","content_type":"<string>","include":"<string>"}}'
```

### News search

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

See [Effort levels](/news/effort-levels), [Filters and sorting](/news/filters), [Writing queries](/news/writing-queries) and [Credits and pricing](/get-started/credits-and-pricing).

`POST /search`

**Estimated cost:** from $0.00109 per call (required params only), up to $0.0109; use `"dryRun": true` in the Run API request to check the exact cost before calling.

**Page:** https://www.orthogonal.com/api/newscatcher-news-api/01eff7e5-a07c-417c-ba17-a226802c0cbb

**Docs:** https://www.newscatcherapi.com/docs/v3/api-reference/overview/introduction

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `q` | string | Yes | 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. |
| `effort` | string | No | 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. |
| `limit` | integer | No | 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). |
| `collapse` | string | No | `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). |
| `sort_by` | string | No | 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. |
| `search_window` | string | No | 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`. |
| `sources` | string | No | 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). |
| `languages` | string | No | Only articles in these languages: ISO 639-1 codes, comma-separated or as an array (at most 100). `zh` is searched as `cn`. |
| `countries` | string | No | Only articles from publishers in these countries: ISO 3166-1 alpha-2 codes, comma-separated or as an array (at most 100). |
| `not_sources` | string | No | 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. |
| `not_languages` | string | No | Leave out articles in these languages: ISO 639-1 codes, comma-separated or as an array (at most 100). `zh` is excluded as `cn`. |
| `not_countries` | string | No | Leave out articles from publishers in these countries: ISO 3166-1 alpha-2 codes, comma-separated or as an array (at most 100). |
| `min_newsrooms` | integer | No | Only stories carried by at least this many newsrooms. |
| `content_type` | string | No | `news` (default) keeps real news articles only; `all` returns every article, whatever its type. |
| `include` | string | No | 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). |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"newscatcher-news-api","path":"/search","body":{"q":"<string>","effort":"<string>","limit":"<integer>","collapse":"<string>","sort_by":"<string>","search_window":"<string>","sources":"<string>","languages":"<string>","countries":"<string>","not_sources":"<string>","not_languages":"<string>","not_countries":"<string>","min_newsrooms":"<integer>","content_type":"<string>","include":"<string>"}}'
```

### Story articles

Every distinct article of one story (the articles that report the same event), best sources first, with the number of newsrooms and when the first and the latest article appeared.
Take the story id from the `story.id` of a search result. A successful request (HTTP 200) costs 1 NCC, regardless of the number of articles returned. The rate limits of your plan apply.

See [Stories](/news/stories).

`GET /stories/{story_id}`

**Estimated cost:** $0.00109

**Page:** https://www.orthogonal.com/api/newscatcher-news-api/5063044e-9093-4d88-9d54-993b0410b77e

**Docs:** https://www.newscatcherapi.com/docs/v3/api-reference/overview/introduction

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `story_id` | string | Yes | Path parameter — substitute directly into the endpoint `path`. |
| `limit` | integer | No | Number of articles to return (1 to 500). |

```bash
# Replace {story_id} in "path" with real values before sending
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"newscatcher-news-api","path":"/stories/{story_id}","method":"GET","query":{"limit":"<integer>"}}'
```

### Article list by query

Every article that matches a boolean query, newest first, for you to page through: the last 12 months, with the publisher, the date, the language, the country and a short snippet of
each. Use `/search` to find the best articles for a question; use `/articles` to get all the articles that match your query.

**Query.** `q` takes `AND`, `OR`, `NOT`, parentheses, `"exact phrases"`, `+must`, `-mustnot`, `wild*cards` and `NEAR("a", "b", 5)`. `search_in` chooses where it is searched: the headline, the
body, both (default) or the summary, in the original language or in the English translation.

**Window and paging.** `from_date` and `to_date` set the window (the last 7 days by default, up to 365 days back: an earlier `from_date` is cut to it and the response says `window.clamped`).
`to_date` defaults to the moment of the request and is returned in `window.to`: send it back as `to_date` when you page, so every page covers the same articles. A page holds up to 100
articles and a query reaches it

`GET /articles`

**Estimated cost:** $0.00545

**Page:** https://www.orthogonal.com/api/newscatcher-news-api/851c0a35-d7e5-4fed-a111-eaa10cbd2b14

**Docs:** https://www.newscatcherapi.com/docs/v3/api-reference/overview/introduction

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `q` | string | Yes | The boolean query: `AND`, `OR`, `NOT`, parentheses, `"exact phrases"`, `+must`, `-mustnot`, `wild*cards` and `NEAR("a", "b", 5)` (the words within 5 of each other). Terms and phrases are searched in the fields of `search_in`. |
| `search_in` | string | No | Where `q` is searched, comma-separated or as an array (at most 2): `title`, `body`, `title_body` (default), `summary`, and the same on the English translation: `title_translated`, `body_translated`, `title_body_translated`, `summary_translated`. A match anywhere in the article counts; the response carries the fields listed in `results`. |
| `from_date` | string | No | Start of the window: ISO 8601 (`2026-10-03`, `2026-10-03T14:00:00`, with or without an offset; UTC otherwise) or a phrase such as `7 days ago`. Default: midnight 7 days ago. Up to 365 days back (an earlier start is cut to it and the response says `window.clamped`). |
| `to_date` | string | No | End of the window, in the same formats. Default: the moment of the request. The response returns it in `window.to`: send it back when paging, so every page covers the same articles. |
| `sources` | string | No | Only these publishers: domains, comma-separated or as an array (at most 100). A domain with a subdomain (`news.bbc.co.uk`) matches that subdomain only. |
| `not_sources` | string | No | Leave out these publishers: domains, comma-separated or as an array (at most 100). Only bare domains (`cnn.com`) leave anything out; a list made of subdomains only (`edition.cnn.com`) excludes nothing. |
| `predefined_sources` | string | No | Only the best-ranked publishers of a country or of the world: `top <n> <country code>` or `top <n> global`, for example `top 100 US`; combined with `sources`. |
| `languages` | string | No | Only articles in these languages: ISO 639-1 codes, comma-separated or as an array (at most 100). `zh` means `cn` and `tw`. |
| `not_languages` | string | No | Leave out articles in these languages: ISO 639-1 codes, comma-separated or as an array (at most 100). `zh` means `cn` and `tw`. |
| `countries` | string | No | Only articles from publishers in these countries: ISO 3166-1 alpha-2 codes, comma-separated or as an array (at most 100). Ignored when `sources` is set. |
| `not_countries` | string | No | Leave out articles from publishers in these countries: ISO 3166-1 alpha-2 codes, comma-separated or as an array (at most 100). Ignored when `sources` is set. |
| `sort_by` | string | No | The order of the results: `published_at` (default) newest first, `-published_at` oldest first, `relevancy` best match first, `rank` best-ranked publisher first. |
| `page` | integer | No | Page number, from 1. `page` x `page_size` is at most 1,000: a query returns up to its first 1,000 articles. |
| `page_size` | integer | No | Articles per page (1 to 100; a plan may allow fewer: the request is refused with 403 above it). |
| `ranked_only` | boolean | No | Only articles from publishers that have a rank. |
| `from_rank` | integer | No | Only publishers ranked at this position or lower (a larger number): the rank is the publisher's traffic rank, 1 being the best. 1 to 999999. Combined with `sources`, an article that matches either passes. |
| `to_rank` | integer | No | Only publishers ranked at this position or better (a smaller number). 1 to 999999. |
| `word_count_min` | integer | No | Only articles of at least this many words (`0` is a filter too: articles without a word count are left out); must be lower than `word_count_max`. |
| `word_count_max` | integer | No | Only articles of at most this many words. |
| `exclude_duplicates` | boolean | No | Leave out copies of an article that another publisher published first. Off by default: the endpoint returns every match. Needs a window that starts after 2024-05-13 for English only (`languages=en`) and after 2025-03-17 otherwise. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"newscatcher-news-api","path":"/articles","method":"GET","query":{"q":"<string>","search_in":"<string>","from_date":"<string>","to_date":"<string>","sources":"<string>","not_sources":"<string>","predefined_sources":"<string>","languages":"<string>","not_languages":"<string>","countries":"<string>","not_countries":"<string>","sort_by":"<string>","page":"<integer>","page_size":"<integer>","ranked_only":"<boolean>","from_rank":"<integer>","to_rank":"<integer>","word_count_min":"<integer>","word_count_max":"<integer>","exclude_duplicates":"<boolean>"}}'
```

### Article list by query

Every article that matches a boolean query, newest first, for you to page through: the last 12 months, with the publisher, the date, the language, the country and a short snippet of
each. Use `/search` to find the best articles for a question; use `/articles` to get all the articles that match your query.

**Query.** `q` takes `AND`, `OR`, `NOT`, parentheses, `"exact phrases"`, `+must`, `-mustnot`, `wild*cards` and `NEAR("a", "b", 5)`. `search_in` chooses where it is searched: the headline, the
body, both (default) or the summary, in the original language or in the English translation.

**Window and paging.** `from_date` and `to_date` set the window (the last 7 days by default, up to 365 days back: an earlier `from_date` is cut to it and the response says `window.clamped`).
`to_date` defaults to the moment of the request and is returned in `window.to`: send it back as `to_date` when you page, so every page covers the same articles. A page holds up to 100
articles and a query reaches it

`POST /articles`

**Estimated cost:** $0.00545

**Page:** https://www.orthogonal.com/api/newscatcher-news-api/0a98bc91-c4d6-4da5-b2e0-bd3b5db3e862

**Docs:** https://www.newscatcherapi.com/docs/v3/api-reference/overview/introduction

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `q` | string | Yes | The boolean query: `AND`, `OR`, `NOT`, parentheses, `"exact phrases"`, `+must`, `-mustnot`, `wild*cards` and `NEAR("a", "b", 5)` (the words within 5 of each other). Terms and phrases are searched in the fields of `search_in`. |
| `search_in` | string | No | Where `q` is searched, comma-separated or as an array (at most 2): `title`, `body`, `title_body` (default), `summary`, and the same on the English translation: `title_translated`, `body_translated`, `title_body_translated`, `summary_translated`. A match anywhere in the article counts; the response carries the fields listed in `results`. |
| `from_date` | string | No | Start of the window: ISO 8601 (`2026-10-03`, `2026-10-03T14:00:00`, with or without an offset; UTC otherwise) or a phrase such as `7 days ago`. Default: midnight 7 days ago. Up to 365 days back (an earlier start is cut to it and the response says `window.clamped`). |
| `to_date` | string | No | End of the window, in the same formats. Default: the moment of the request. The response returns it in `window.to`: send it back when paging, so every page covers the same articles. |
| `sources` | string | No | Only these publishers: domains, comma-separated or as an array (at most 100). A domain with a subdomain (`news.bbc.co.uk`) matches that subdomain only. |
| `not_sources` | string | No | Leave out these publishers: domains, comma-separated or as an array (at most 100). Only bare domains (`cnn.com`) leave anything out; a list made of subdomains only (`edition.cnn.com`) excludes nothing. |
| `predefined_sources` | string | No | Only the best-ranked publishers of a country or of the world: `top <n> <country code>` or `top <n> global`, for example `top 100 US`; combined with `sources`. |
| `languages` | string | No | Only articles in these languages: ISO 639-1 codes, comma-separated or as an array (at most 100). `zh` means `cn` and `tw`. |
| `not_languages` | string | No | Leave out articles in these languages: ISO 639-1 codes, comma-separated or as an array (at most 100). `zh` means `cn` and `tw`. |
| `countries` | string | No | Only articles from publishers in these countries: ISO 3166-1 alpha-2 codes, comma-separated or as an array (at most 100). Ignored when `sources` is set. |
| `not_countries` | string | No | Leave out articles from publishers in these countries: ISO 3166-1 alpha-2 codes, comma-separated or as an array (at most 100). Ignored when `sources` is set. |
| `sort_by` | string | No | The order of the results: `published_at` (default) newest first, `-published_at` oldest first, `relevancy` best match first, `rank` best-ranked publisher first. |
| `page` | integer | No | Page number, from 1. `page` x `page_size` is at most 1,000: a query returns up to its first 1,000 articles. |
| `page_size` | integer | No | Articles per page (1 to 100; a plan may allow fewer: the request is refused with 403 above it). |
| `ranked_only` | boolean | No | Only articles from publishers that have a rank. |
| `from_rank` | integer | No | Only publishers ranked at this position or lower (a larger number): the rank is the publisher's traffic rank, 1 being the best. 1 to 999999. Combined with `sources`, an article that matches either passes. |
| `to_rank` | integer | No | Only publishers ranked at this position or better (a smaller number). 1 to 999999. |
| `word_count_min` | integer | No | Only articles of at least this many words (`0` is a filter too: articles without a word count are left out); must be lower than `word_count_max`. |
| `word_count_max` | integer | No | Only articles of at most this many words. |
| `exclude_duplicates` | boolean | No | Leave out copies of an article that another publisher published first. Off by default: the endpoint returns every match. Needs a window that starts after 2024-05-13 for English only (`languages=en`) and after 2025-03-17 otherwise. |

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H 'Authorization: Bearer $ORTHOGONAL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"api":"newscatcher-news-api","path":"/articles","body":{"q":"<string>","search_in":"<string>","from_date":"<string>","to_date":"<string>","sources":"<string>","not_sources":"<string>","predefined_sources":"<string>","languages":"<string>","not_languages":"<string>","countries":"<string>","not_countries":"<string>","sort_by":"<string>","page":"<integer>","page_size":"<integer>","ranked_only":"<boolean>","from_rank":"<integer>","to_rank":"<integer>","word_count_min":"<integer>","word_count_max":"<integer>","exclude_duplicates":"<boolean>"}}'
```

---

Full details and an interactive quickstart: https://www.orthogonal.com/publisher/newscatcher-news-api
