NewAnswers MCP: one question, one checked answer for your agent.See how it works

Product

Deep research APIs: a developer's guide

Updated

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.

Terminal window
# 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 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: pro 2 to 10 minutes, ultra 5 to 25 minutes, ultra8x 5 minutes to 2 hours (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).
  • 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).
  • OpenAI: background requests 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). 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.

Terminal window
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 | 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)
Terminal window
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.