Quickstart

Before you begin

Create an account in the NewsCatcher platform and copy your API key. The same key works for the News API and the agent.

Store the key in an environment variable instead of pasting it into code: export NEWSCATCHER_API_KEY="your key".

Search the news

Send a search

Send your question in q and the key in the x-api-key header:

curl -X POST "https://api.newscatcherapi.com/news-api/search" \
  -H "x-api-key: $NEWSCATCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "hurricane recovery florida", "limit": 5}'

import os
import requests

response = requests.post(
    "https://api.newscatcherapi.com/news-api/search",
    headers={"x-api-key": os.environ["NEWSCATCHER_API_KEY"]},
    json={"q": "hurricane recovery florida", "limit": 5},
)
response.raise_for_status()
for article in response.json()["results"]:
    print(article["published_at"], article["source"]["domain"], article["title"])

const response = await fetch("https://api.newscatcherapi.com/news-api/search", {
  method: "POST",
  headers: {
    "x-api-key": process.env.NEWSCATCHER_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ q: "hurricane recovery florida", limit: 5 }),
});
const { results } = await response.json();
for (const article of results) console.log(article.published_at, article.title);

Read the response

Results come best first. Each article has a one-line summary and the story it belongs to:

{
  "query": "hurricane recovery florida",
  "effort": "medium",
  "sort_by": "relevancy",
  "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."
    }
  ]
}

The search ran at the default medium effort over the last 7 days. Set effort and search_window to change both.

Run the agent

Start a run

Describe the events you need. The run starts in the background:

curl -X POST "https://api.newscatcherapi.com/agent/runs" \
  -H "x-api-key: $NEWSCATCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Bank M&A deals announced in the US since Sep 15", "mode": "fast"}'

The response carries the run_id.

Get the result

A fast run takes about 1 to 3 minutes. Poll the run until its status is no longer queued or running. When it is succeeded, read its columns and rows:

curl "https://api.newscatcherapi.com/agent/runs/RUN_ID" \
  -H "x-api-key: $NEWSCATCHER_API_KEY"

To follow the run live instead, open its progress stream.

Next steps

Effort levels

Trade speed and price for ranking quality.

Agent modes

Events or companies, once or kept up to date.

Get started

News API

Agent

Resources

Before you begin

Search the news

Run the agent

Next steps

Effort levels

Agent modes

​Before you begin

​Search the news

​Run the agent

​Next steps

Effort levels

Agent modes

Before you begin

Search the news

Run the agent

Next steps