DeepResearch

DeepResearch is the research report API. Provide a topic, and the service runs multiple rounds of retrieval, cross-checks sources, and produces a cited report with artifacts. It is a one-shot asynchronous research task — not an alias of DoAnything, and not a synchronous function. This page introduces the problems it solves and its core capabilities first, then the current call surface.

What it solves

• Research is a pipeline, not a single search: a deliverable conclusion requires framing the question, planning, multi-round retrieval, cross-checking, and drafting. Orchestrating that yourself over search and browser APIs is expensive; DeepResearch packages the whole pipeline into one run.
• Reports must be traceable: results carry citations_count and confidence_summary, and the body supports its claims with citations instead of an unsourced summary.
• Sources and depth must be controllable: domain_whitelist / domain_blacklist constrain sources, depth controls retrieval depth, and target_audience sets the drafting perspective — no runaway "longer is better" research.
• Follow-ups do not start over: a run accepts follow-up messages, and a new run can pass session_id to reuse the existing research context.

Core capabilities

Capability	Description
Full-pipeline research	A single run moves through brief, plan, gather, crosscheck, and synthesize
Depth levels	depth supports light / standard / deep, defaulting to standard
Source control	domain_whitelist / domain_blacklist constrain or exclude domains
Audience targeting	target_audience sets the intended reader and drafting angle
Structured output	Returns a final_md report and artifacts, with citation count and a confidence summary
Observable progress	SSE events track each phase; runs can be canceled
Follow-up and feedback	REST endpoints for follow-up and feedback (no SDK methods yet)

Typical scenarios

• Industry and technology trend reports: provide a topic, get a cited multi-source review.
• First drafts of competitive and market research, refined and verified by humans afterwards.
• Reports aimed at a specific reader, with target_audience controlling depth and framing.

When to use it

• The deliverable is a drafted report, not a list of search hits or page actions.
• Claims need citations and readers must be able to trace every conclusion.
• Minutes-to-hours asynchronous execution is acceptable.

For structured search results only, use WebSearch; to act inside specific sites, use DoAnything; to watch a set of pages over time, use Track.

Request

POST /api/v1/projects/{pid}/deep_research/runs
Authorization: Bearer wa_...
Content-Type: application/json

The supported fields are topic (required), depth (light / standard / deep), output_format (report), target_audience, domain_whitelist, domain_blacklist, max_duration_minutes, and optional session_id for a follow-up run.

Node SDK

const research = await qoni.deepResearch.run({
  token,
  prompt: "Research the main browser-automation trends in 2026.",
  depth: "standard",
  limits: { maxDurationMinutes: 120 },
});
const result = await research.wait();
console.log(result.status, result.output);
for (const artifact of result.artifacts) {
  console.log(artifact.id, (await artifact.content()).length);
}

The create endpoint returns 202; wait() waits for the terminal run. The current phases are brief, plan, gather, crosscheck, and synthesize.

The result payload contains final_md, final_artifact_id, citations_count, confidence_summary, and possibly partial_sections.

Events and follow-up

GET  /api/v1/projects/{pid}/deep_research/runs/{run_id}/events
POST /api/v1/projects/{pid}/deep_research/runs/{run_id}/cancel
GET  /api/v1/projects/{pid}/deep_research/runs/{run_id}/artifacts

Follow-up and feedback are REST-only today; the current SDK (@qoniai/qoni 0.4.1) exposes no methods for them:

POST /api/v1/projects/{pid}/deep_research/runs/{run_id}/messages
Content-Type: application/json

{ "text": "Add 2025 data." }

POST /api/v1/projects/{pid}/deep_research/runs/{run_id}/feedback
Content-Type: application/json

{ "thumbs": "up" }

feedback also accepts rating and feedback_text. To start another round of research reusing existing context, pass session_id on create instead of appending messages to a terminal run.

There is no current DeepResearch /intervene endpoint.