# Research (/docs/api/gateway/research)

Asynchronous deep research: a cited report from several searches and page reads.

`POST /v1/research` starts a job that plans several searches, reads the best pages and writes a report where every claim cites its source as `[S1]`..`[Sn]` (or, with `output_schema`, a JSON `answer`). The request waits up to `wait_s` seconds (default 0) and answers 200 with the finished job or 202 while it is `queued` / `running`; poll `GET /v1/research/{id}` until `status` is `done` or `failed`. Resending the same `Idempotency-Key` returns the existing job. Admission is the same as [tools](./tools.mdx) — your rules see it as `web_search`. Price: $0.20 per job plus its model tokens; jobs inside the monthly free allowance or a codai agent turn are not charged the job fee.

The SDKs wrap the polling: `codai.research.run({ question })` (TypeScript) and `codai.research.run("…")` (Python) start the job and wait for it. The same engine is the `deep_research` tool in VS Code, desktop, phone, headless and the hosted MCP. Details: [tools guide](../../agents/tools.mdx#deep-research--v1research).

<OpenAPIPage document="./openapi/en/gateway.yaml" operations={[{path: '/v1/research',method: 'post'},{path: '/v1/research/{id}',method: 'get'}]} />