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

# Agent quickstart

> Start a run, follow it, and download the result.

**1. Start a run**

```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",
    "max_rows": 50
  }'
```

The run is queued and you get its id:

```json theme={null}
{ "run_id": "RUN_ID", "status": "queued", "kind": "events" }
```

**2. Follow it**

Poll `GET /runs/{run_id}` until `status` is no longer `queued` or
`running`:

```python theme={null}
import os
import time
import requests

BASE = "https://api.newscatcherapi.com/agent"
HEADERS = {"x-api-key": os.environ["NEWSCATCHER_API_KEY"]}

run = requests.post(
    f"{BASE}/runs",
    headers=HEADERS,
    json={"query": "Bank M&A deals announced in the US since Sep 15", "mode": "fast"},
).json()

while True:
    detail = requests.get(f"{BASE}/runs/{run['run_id']}", headers=HEADERS).json()
    if detail["status"] not in ("queued", "running"):
        break
    time.sleep(15)

if detail["status"] != "succeeded":
    raise RuntimeError(detail.get("error"))
print(detail["columns"])
for row in detail["rows"]:
    print(row)
```

Or open the [progress stream](/docs/agent/runs.md#follow-a-run-live) to see each
step as it happens.

**3. Download the table**

```bash theme={null}
curl -o deals.csv "https://api.newscatcherapi.com/agent/runs/RUN_ID/export.csv" \
  -H "x-api-key: $NEWSCATCHER_API_KEY"
```

`export.xlsx` gives the same table as an Excel file.

**4. Keep it updated (optional)**

Turn the succeeded run into a monitor that delivers new deals every week:

```bash theme={null}
curl -X POST "https://api.newscatcherapi.com/agent/monitors" \
  -H "x-api-key: $NEWSCATCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "dataset", "from_run_id": "RUN_ID", "schedule": {"every": "week"}}'
```


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