# Deep research APIs: a developer's guide

A deep research API takes one question, runs a search, read and write loop on the vendor's servers for minutes or hours, and returns a report with citations. That one fact shapes every integration: the call outlives an HTTP request, the bill depends on how much the loop did, and the citations are only as good as whatever checked them. This guide covers the decisions a deep research API forces on you, compares the main APIs from their own documentation, and ends with the request and response for ours. We make Hyperresearch, which is one row in the table. Every vendor fact below was read on that vendor's docs on November 19, 2026.

## Four decisions you make before writing code

### 1. How you learn the job is done

[RFC 9110](https://www.rfc-editor.org/rfc/rfc9110.html) defines `202 Accepted` as a request "accepted for processing, but the processing has not been completed", and notes that HTTP has no way to send the final status of an asynchronous operation later. So every API here hands you an id and leaves you three ways to wait: poll, stream, or receive a webhook.

```bash
# OpenAI: start in background mode, then poll the response id
curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"gpt-6.2-astra","reasoning":{"effort":"xhigh"},"background":true,
       "tools":[{"type":"web_search"}],"input":"<question>"}'
curl https://api.openai.com/v1/responses/resp_123 -H "Authorization: Bearer $OPENAI_API_KEY"
```

`gpt-6.2-astra` at `high` or `xhigh` effort is what OpenAI's [web search guide](https://developers.openai.com/api/docs/guides/tools-web-search) names for multi-step research, as read on November 19, 2026. The dedicated `o3-deep-research` and `o4-mini-deep-research` models were shut down on July 23, 2026 ([deprecations](https://developers.openai.com/api/docs/deprecations)). The [background mode guide](https://developers.openai.com/api/docs/guides/background) says to keep polling while the status is `queued` or `in_progress`, cancel with `POST /v1/responses/{id}/cancel`, and resume a dropped stream by passing the last `sequence_number` as `starting_after`.

Webhooks save the polling, but you inherit their failure modes. OpenAI's [webhooks](https://developers.openai.com/api/docs/guides/webhooks) fire `response.completed`, follow the Standard Webhooks headers, retry "for up to 72 hours with exponential backoff", and can arrive twice, so use the `webhook-id` header as an idempotency key. Parallel takes a `webhook` object on the task run with one event type, `task_run.status`, signed with HMAC ([Parallel webhooks](https://docs.parallel.ai/task-api/webhooks)). Gemini's and Perplexity's background-mode pages describe polling and streaming and mention no webhooks.

Retrying the POST that starts a billed job is the other trap. The [Idempotency-Key header](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/) exists to make POST "fault-tolerant", but it is still an IETF draft (version 08, dated October 22, 2026), so check whether each vendor honours it.

### 2. Timeouts

Never hold a connection open for a report. Store the id, set your own deadline, and treat "incomplete" as a real outcome. Documented durations vary widely:

- Gemini Deep Research: "Most tasks should complete within 20 minutes", with a maximum research time of 60 minutes ([docs](https://aistudio.google.com/docs/deep-research)).
- Parallel Task API: `pro` 2 to 10 minutes, `ultra` 5 to 25 minutes, `ultra8x` 5 minutes to 2 hours ([pricing](https://docs.parallel.ai/getting-started/pricing)).
- You.com Research API: `frontier` effort runs 30 s to 12,000 s with a median of 300 s and requires `background: true` ([reference](https://you.com/docs/api-reference/research/v1-research)).
- Perplexity Agent API: a background run ends `completed`, `failed`, `cancelled` or `incomplete`; one paused at your organization's token limit stays `in_progress`, and the docs say not to resubmit it ([background mode](https://docs.perplexity.ai/docs/agent-api/background-mode)).
- OpenAI: [background requests](https://developers.openai.com/api/docs/guides/background) take a completion window of `soonest`, `2h` or `8h`; the two slower windows are priced 30% and 40% below standard token rates.

### 3. Billing by tokens or by task

Token billing tracks effort, so you know the price only after the run. OpenAI charges model tokens plus $10.00 per 1,000 web search calls, with search content billed as tokens at model rates ([pricing](https://developers.openai.com/api/docs/pricing)). Perplexity's Agent API bills tokens plus $0.0025 per standard web search and $0.0005 per URL fetch ([pricing](https://docs.perplexity.ai/getting-started/pricing)). Gemini bills tokens and tool fees, and Google estimates about $1 to $3 a task for Deep Research and $3 to $7 for Max, "subject to change". Per-task pricing gives you a number up front: Parallel charges per run and does not bill failed runs; You.com charges $12 to $1,200 per 1,000 calls by effort ([pricing](https://you.com/docs/pricing)).

### 4. What a citation is, and whether anything checks it

OpenAI returns `url_citation` annotations with `start_index`, `end_index`, `url` and `title`, plus a `sources` list that is "often greater than the number of citations". Parallel's [research basis](https://docs.parallel.ai/task-api/guides/access-research-basis) gives each output field citations with excerpts, a reasoning note and a high, medium or low confidence rating. You.com returns numbered citations into a `sources` array with URL, title and snippets. Google recommends "reviewing the `citations` provided in the response to verify the sources". None of the vendor pages read for this guide describe a step that re-reads each cited source to confirm it supports its sentence. If your users will act on the report, plan for that check yourself; [how to verify citations in AI output](/guides/verify-citations-in-ai-output) walks through it.

## The APIs side by side

Read November 19, 2026, from each vendor's docs linked above.

| API | Waiting | Documented time | Billing | Citations returned |
|---|---|---|---|---|
| OpenAI Responses API, `web_search` | Background mode; poll, stream or webhook | "Several minutes" | Tokens plus $10 per 1,000 searches | Character span, URL, title; `sources` list |
| Gemini Deep Research agent (preview; `deep-research-preview-04-2026`, `deep-research-max-preview-04-2026`) | Interactions API, `background=true`; poll or stream | Most under 20 min, 60 min cap | Tokens plus tool fees; about $1 to $7 a task, estimated | Citations in the response; no structured outputs |
| Perplexity Agent API, `high` preset | Background mode; poll or stream | At most 40 tool calls ([presets](https://docs.perplexity.ai/docs/agent-api/presets)) | Tokens plus tool fees | Inline `[web:n]` citations |
| Parallel Task API | Poll or webhook | 2 min to 2 hr by processor | $100 to $2,400 per 1,000 runs (`pro` to `ultra8x`) | Per field, with excerpts and confidence |
| You.com Research API | Sync, or background with poll or stream | Under 10 s to 12,000 s by effort | $12 to $1,200 per 1,000 calls | Numbered, with snippets |
| Messari Deep Research (crypto only) | Create, poll, retrieve | "Typically take 5-10 minutes" | 500 credits a request ([docs](https://docs.messari.io/api-reference/endpoints/ai/deep-research-api)) | Report sources |
| Hyperresearch | Poll, event stream or webhook | 30 to 40 min Light, 3 to 5 h Deep (targets) | Flat per run, price returned at creation ([pricing](/pricing)) | Numbered citations, checked against their sources before shipping |

Pick by job. For a JSON schema filled field by field at thousands of rows a day, Parallel fits. If your app already runs on OpenAI or Gemini and a report in minutes is enough, staying put keeps one vendor and one bill. For deeper vendor detail, see [the OpenAI deep research API after the shutdown](/alternatives/openai-deep-research-api), [Gemini Deep Research compared](/alternatives/gemini-deep-research), [Parallel Task API compared](/alternatives/parallel-task-api) and [deep research APIs with citations, compared](/guides/research-api-with-citations).

## The Hyperresearch request and response

From the quickstart. `tier` is `light` or `premier`, and `premier` is Deep.

```bash
curl https://api.hyperresearch.ai/v1/runs \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: research-2026-09-14-01" \
  -d '{"query":"What changed in grid-scale storage policy?","tier":"light"}'
```

The `202` body, as the `RunCreated` schema in the [OpenAPI document](https://api.hyperresearch.ai/v1/openapi.json) defines it:

```text
id            string    "run_01J9ZQ7V6H0000000000000000"
status        queued | clarifying
tier          light | premier
price_cents   integer, fixed before work starts; null while clarifying
events_url    "/v1/runs/{id}/events"
created_at    string
clarification present when status is clarifying (up to three questions)
```

```bash
curl https://api.hyperresearch.ai/v1/runs/run_01J9.../result \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

| Field in the result | What it holds |
|---|---|
| `report_markdown` | The report, with numbered citations |
| `sources` | Every kept source |
| `skipped` | Every page tried and not kept, with a reason |
| `claims` | The claims the report relies on, with their support |
| `verification` | The checks the report passed or failed |
| `attention` | Findings to read before relying on the report |

Poll `GET /v1/runs/{id}` about once a minute (the status bucket allows 600 calls a minute per key), stream the events, or subscribe a console [webhook](/docs/webhooks); deliveries can repeat, so deduplicate by delivery id. Retry a POST only with the same idempotency key and an unchanged body. Keys that start `hr_test_` run the real lifecycle free, with placeholder writing. Agents get the same runs over MCP; [long-running runs over MCP](/mcp/long-running-runs) explains the start-and-poll pattern.

What the run does differently is the fourth decision above. Both tiers check cited claims against their sources and correct what does not hold before the report ships; Deep adds a [verification receipt](/verification-receipt) with a verdict for each checked citation. On ten DRACO tasks, Hyperresearch Deep scored 77.7 ([method and every task score](/benchmarks/draco)). The limits are plain: a run takes half an hour or more, it returns a report rather than your JSON schema, and it reads public pages only. For one fact with a checked quote in seconds, [Answers](/answers) is the better call. For the product side rather than the API, see [deep research AI](/deep-research-ai), or read a [finished Deep report](/samples/ai-coding-agents).

## Starting

Create a key at the [console](https://console.hyperresearch.ai/login) with `runs:write` and `runs:read`, build against an `hr_test_` key, then switch to live. Your first Light report is free when you sign up, with no card. Every endpoint is in the [API reference](/docs/api).
