# Run deep research with cited reports

> Async deep research with /v1/research: Claude plans Google searches, reads and ranks the pages and writes a cited report. Efforts, polling, webhooks, pricing.

Some questions need many searches and many pages: "compare the managed Postgres offerings in the EU", "what changed in this regulation this year". [`POST /v1/research`](https://serpkite.com/docs/endpoints/research) runs that work in the background and returns a Markdown report in which every claim cites a numbered source.

## How a task runs

1. **Plan.** Claude turns your `input` into a first round of Google queries.
2. **Search and read.** Each query runs on Google; the top pages are read and their passages ranked against the task.
3. **Check.** A decision model (OpenAI's Decisions API) asks whether the notes already cover the task, and drops sources that are off-topic.
4. **Fill gaps.** If something is missing, Claude plans follow-up queries for the next round.
5. **Write.** Claude writes the report: a summary first, then sections, tables and caveats, with `[n]` citations.

| `effort` | First-round queries | Rounds | Pages per query | Credits |
| --- | ---: | ---: | ---: | ---: |
| `lite` | 3 | 1 | 2 | 30 |
| `standard` | 5 | 2 | 3 | 75 |
| `deep` | 8 | 3 | 4 | 200 |

## Start a task and wait for the report

cURL:

```bash
curl https://api.serpkite.com/v1/research \
  -H "Authorization: Bearer $SERPKITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"compare espresso machines under $500 for a small office","effort":"standard"}'
```

TypeScript:

```ts
import { SerpKite } from "serpkite";

const sk = new SerpKite(); // reads SERPKITE_API_KEY
const res = await sk.research({ input: "compare espresso machines under $500 for a small office", effort: "standard" });
const done = await sk.waitResearch(res);
console.log(done.status, done.result?.report);
```

`POST /v1/research` answers `202` with the task's `id` and `poll_url`. Poll `GET /v1/research/{id}` (free) until `status` is `completed`, `failed` or `canceled`. While it runs, `progress` shows the `round`, `rounds`, `queries` and `sources` so far and the current `step` (`searching`, `reviewing` or `writing`). Lite usually finishes in under a minute; deep in a few minutes.

```bash
curl https://api.serpkite.com/v1/research/01926a3e-8c4d-7e1f-a2b3-c4d5e6f7a8b9 \
  -H "Authorization: Bearer $SERPKITE_API_KEY"
```

## What the result holds

| Field | What |
| --- | --- |
| `result.report` | The Markdown report with `[n]` citation markers |
| `result.citations[]` | The sources the report cites: `index`, `title`, `link`, `domain` |
| `result.sources[]` | Every source read, with `published_at` and the `query` that found it |
| `result.queries[]` | Every Google query the task ran |
| `result.stats` | `searches`, `sources`, `rounds` |
| `result.output` | With `output_schema`: a JSON value that matches it (`output_error` when it couldn't be produced; the report still counts) |

Results are kept for 24 hours after the task ends.

## Use a webhook instead of polling

Send `webhook_url` (or set an account webhook in the dashboard) and SerpKite POSTs a signed `research.completed` event when the task completes, fails or is canceled. The body is the task with its `result`, signed like every other [webhook](https://serpkite.com/docs/webhooks): verify `X-SerpKite-Signature` before trusting it.

## Scope the sources

- `include_domains` and `exclude_domains` (up to 20 each) keep the research to filings, official sites or the press you trust.
- `country` and `language` set where and in which language the searches run.
- `output_schema` (up to 16 KB) returns the findings as typed fields next to the report, for enrichment pipelines.

## Pricing, cancellation and limits

- The flat price (30, 75 or 200 credits) is reserved when the task is queued and charged only when the report is written. A task that fails is refunded in full.
- `DELETE /v1/research/{id}` cancels a task: a queued one is refunded at once; a running one stops at its next round and is charged 1 credit per search already run.
- Research and crawl tasks share a limit of 20 queued or running tasks per account; more return `429`.
- The remote [MCP server](https://serpkite.com/docs/mcp) has `research` and `research_result` tools.

## Privacy

The input, the planned queries and the page text are sent to Anthropic (writing) and OpenAI (decision checks) under API terms that exclude training. SerpKite never logs them; the task's request is cleared when it ends and the result is deleted 24 hours later. See [Privacy and data retention](https://serpkite.com/docs/privacy-and-data-retention#ai-features).

## Related

- [Research reference](https://serpkite.com/docs/endpoints/research): Every parameter, field and status of /v1/research.
- [Cited answers](https://serpkite.com/docs/guides/cited-answers): One question, one cited answer, in seconds.
- [Webhooks](https://serpkite.com/docs/webhooks): Signed deliveries and how to verify them.
- [AI pricing](https://serpkite.com/docs/credits-and-billing#ai-features): What research and answers cost.