Deep Research
Generates a deep research report at the selected tier. The pro-visual tier also returns relevant images and videos.
Two-phase invocation
- Phase 1: the server generates a research plan. If the plan has no ambiguity, the server proceeds directly to research and streams the final report. If the plan is ambiguous, the
planevent carriesrequires_selection=truetogether with aplan_id, and the SSE stream ends there — waiting for the client to confirm. - Phase 2: call this endpoint again with the
plan_idandselections. The server loads the stored plan, applies the selections, and streams the final report.
Notes
- Phase 2 only inherits the stored
planviaplan_id. Other parameters are NOT inherited from Phase 1 — they must be supplied again in Phase 2, otherwise they fall back to defaults. messagesis required in both phases and should carry the same user question.
Authorizations
Bearer token used for request authentication. Alternatively, you can send the API key in the x-api-key header. Note: A payment method is required to use the API.
Body
Request body for the Deep Research API.
Conversation messages. Only the last role=user message is used as the research question; other messages are ignored and do not enter plan generation, search, analysis, or report writing.
The research tier. lite, standard, and pro increase research depth, cost, and time in that order. pro-visual additionally illustrates each report section with images and videos and streams an HTML version of the report.
lite, standard, pro, pro-visual Additional research background, constraints, or preferences, used as extra context for query rewriting and research direction supplementation.
Skip the Research Brief stage and write the final report directly from raw search and analysis results.
Note: when enabled, no brief event is emitted. Clients can rebuild the citation index by accumulating search_results events in the order they arrive (round-by-round / query-by-query / result-by-result) into a global index, then look up the corresponding url/title by the N in [^N].
Phase 1 only. Skip the Research Plan stage and proceed straight to the search loop. With skip_plan=true, the call never enters the Phase 2 pause mechanism.
Phase 1 only. When true, the run continues with all angles even if the plan is ambiguous, instead of pausing and waiting for the user to confirm a selection.
Phase 2 only. The plan ID returned by a Phase 1 plan event with requires_selection=true. When provided, the server skips plan generation and applies the supplied selections against the stored plan. Each plan_id is retained for 30 minutes; after expiry the plan is regenerated.
Phase 2 only. The user's corrections and angle filtering against the Phase 1 plan.
Response
Successful Deep Research response. Always streamed as Server-Sent Events.
A streaming chunk of a Deep Research response.
The unique identifier for this request.
Unix timestamp (in seconds) of when the chunk was created.
The type of this streaming chunk. On the pro-visual tier, html_delta chunks stream an HTML version of the report after the report content completes, and a final html chunk marks the end of that stream.
status, plan, queries, search_done, analysis, brief, content, visual, html_delta, html, finish, usage, error The object type, always research.chunk.
research.chunk Current research round. Present only in queries, search_done, and analysis chunks.
Latency in milliseconds for the stage represented by this chunk.
Pipeline progress copy. Present only in status chunks.
Research plan generated in Phase 1. Carried by plan chunks.
Plan ID carried by plan chunks. The client must echo this back as plan_id when entering Phase 2.
Sub-queries generated for this round. Present only in queries chunks.
Total number of search results returned this round. Present only in search_done chunks.
Search results for this round, one group per sub-query. Present only in search_done chunks.
Analysis output for one research round. Carried by analysis chunks.
Report outline and evidence set. Carried by brief chunks.
Incremental choices for the final report. Present in content and finish chunks.
Visual material for one report section. Present only in visual chunks, emitted on the pro-visual tier.
An incremental fragment of the HTML report. Present only in html_delta chunks. Concatenate the fragments in order to rebuild the full page.
Usage and latency metadata for the Deep Research call. Carried by usage chunks.