Deep Research
Generates a deep research report. Always returns Server-Sent Events.
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, pro 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 model used for this completion.
The type of this streaming chunk.
status, plan, queries, search_done, analysis, brief, content, 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.
Usage and latency metadata for the Deep Research call. Carried by usage chunks.