> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get an API key and make your first News API search and agent run.

## Before you begin

[Create an account in the NewsCatcher platform](https://platform.newscatcherapi.com)
and copy your API key. The same key works for the News API and the agent.

> [!TIP]
>
> Store the key in an environment variable instead of pasting it into code:
> `export NEWSCATCHER_API_KEY="your key"`.

## Search the news

**1. Send a search**

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

```bash cURL theme={null}
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}'
```

```python Python theme={null}
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"])
```

```javascript JavaScript theme={null}
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);
```

**2. Read the response**

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

```json theme={null}
{
  "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](/docs/news/effort-levels.md) over
the last 7 days. Set `effort` and `search_window` to change both.

## Run the agent

**1. Start a run**

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

```bash theme={null}
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`.

**2. 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`:

```bash theme={null}
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](/docs/agent/runs.md#follow-a-run-live).

## Next steps

> [card] [Effort levels](/docs/news/effort-levels.md)
>
> Trade speed and price for ranking quality.

> [card] [Agent modes](/docs/agent/overview.md)
>
> Events or companies, once or kept up to date.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.