# Research a topic

A longer run that answers, looks for what is missing, reads more and answers again.

`POST /research`

Research is a run, not a single call. The request answers at once with 202 and a run id. The run then answers the question, finds the claims it could not support, reads more pages for them and answers again, up to three rounds. Needs the scope `search:read`.

| Field | Type | Meaning |
| --- | --- | --- |
| `query` | string | Required. The research question, 1 to 1,000 characters. |
| `webhookUrl` | string | Optional. An https address that is sent the final state when the run ends. |
| `maxIterations` | number | Optional. How many rounds to run, 1 to 3. The default is 3. |

Request:

```
curl -sS https://api.rivier.ai/research \
  -H "Authorization: Bearer $RIVIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "opening hours of the national library" }'
```

Response:

```
{
  "run_id": "run_5c1f…",
  "status": "queued"
}
```

## Follow a run

`GET /research/{id}` answers the state and, when the run has ended, the result. `GET /research/{id}/events` is the progress as a server-sent stream; reconnect with `Last-Event-ID`. `POST /research/{id}/cancel` stops the run. `GET /research/budget` says what research may still spend this period.

The result has the same shape as an [answer](https://rivier.ai/docs/answer.md), with the number of rounds that ran.