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 plan event carries requires_selection=true together with a plan_id, and the SSE stream ends there — waiting for the client to confirm.
  • Phase 2: call this endpoint again with the plan_id and selections. The server loads the stored plan, applies the selections, and streams the final report.

Notes

  • Phase 2 only inherits the stored plan via plan_id. Other parameters are NOT inherited from Phase 1 — they must be supplied again in Phase 2, otherwise they fall back to defaults.
  • messages is required in both phases and should carry the same user question.
post/v1/research

Request

  • Base URL: https://api.octen.ai
  • URL: https://api.octen.ai/v1/research
  • Auth: one of:
    • HTTP bearer
    • API key in header x-api-key

Request body

tier'lite' | 'standard' | 'pro' | 'pro-visual'

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.

extra_contextstring

Additional research background, constraints, or preferences, used as extra context for query rewriting and research direction supplementation.

skip_briefboolean

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].

skip_planboolean

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.

skip_plan_confirmboolean

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.

plan_idstring

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.

Response

Successful Deep Research response. Always streamed as Server-Sent Events.

type'status' | 'plan' | 'queries' | 'search_done' | 'analysis' | 'brief' | 'content' | 'visual' | 'html_delta' | 'html' | 'finish' | 'usage' | 'error'

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.

request_idstring required

The unique identifier for this request.

object'research.chunk'

The object type, always research.chunk.

creatednumber required

Unix timestamp (in seconds) of when the chunk was created.

roundinteger

Current research round. Present only in queries, search_done, and analysis chunks.

latencyinteger

Latency in milliseconds for the stage represented by this chunk.

statusstring

Pipeline progress copy. Present only in status chunks.

plan_idstring

Plan ID carried by plan chunks. The client must echo this back as plan_id when entering Phase 2.

queriesstring[]

Sub-queries generated for this round. Present only in queries chunks.

search_result_countinteger

Total number of search results returned this round. Present only in search_done chunks.

Changes

No recorded changes to this operation across all 1 revision of this API.