Product
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 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.
# OpenAI: start in background mode, then poll the response idcurl 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 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). The background mode guide 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 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). 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 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).
- Parallel Task API:
pro2 to 10 minutes,ultra5 to 25 minutes,ultra8x5 minutes to 2 hours (pricing). - You.com Research API:
frontiereffort runs 30 s to 12,000 s with a median of 300 s and requiresbackground: true(reference). - Perplexity Agent API: a background run ends
completed,failed,cancelledorincomplete; one paused at your organization’s token limit staysin_progress, and the docs say not to resubmit it (background mode). - OpenAI: background requests take a completion window of
soonest,2hor8h; 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). Perplexity’s Agent API bills tokens plus $0.0025 per standard web search and $0.0005 per URL fetch (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).
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 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 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) | 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) | 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) | 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, Gemini Deep Research compared, Parallel Task API compared and deep research APIs with citations, compared.
The Hyperresearch request and response
From the quickstart. tier is light or premier, and premier is Deep.
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 defines it:
id string "run_01J9ZQ7V6H0000000000000000"status queued | clarifyingtier light | premierprice_cents integer, fixed before work starts; null while clarifyingevents_url "/v1/runs/{id}/events"created_at stringclarification present when status is clarifying (up to three questions)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; 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 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 with a verdict for each checked citation. On ten DRACO tasks, Hyperresearch Deep scored 77.7 (method and every task score). 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 is the better call. For the product side rather than the API, see deep research AI, or read a finished Deep report.
Starting
Create a key at the console 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.
