Build a research feature with the DeepResearch API

A research feature needs more than a report. Users need to know what is running, where the evidence came from, and what to do when a task needs attention. This guide connects the DeepResearch quickstart to an application your team can operate.

Define the job before the prompt

Choose one repeatable output: a company overview, a competitor comparison, or a scientific evidence summary. Specify the subject, period, questions and evidence the user expects to see. For a company comparison, a useful request names the companies and comparison criteria. “Research this market” leaves both the scope and the definition of a useful result open.

from valyu import Valyu

valyu = Valyu()
task = valyu.deepresearch.create(
    query="Compare Microsoft and Alphabet's cloud businesses using their 2025 annual reports.",
    mode="standard",
    research_strategy="Prioritize annual reports and investor relations material. "
                      "Distinguish reported segment figures from estimates.",
    report_format="Use sections for business scope, reported revenue, growth drivers, "
                  "and limitations. Cite the source for each financial figure.",
)
print(task.deepresearch_id)

Keep instructions about finding evidence in research_strategy and instructions about presentation in report_format. If downstream code needs fields, use structured output rather than parsing headings from prose.

Keep the task outside the page request

Store the returned deepresearch_id with your application’s user and request record. Return a pending state to your frontend, then track the task from a backend worker or webhook handler.

State	What your application should do
`queued` or `running`	Show progress and keep the existing task ID
`awaiting_input` or `paused`	Display the checkpoint if you enabled human review
`completed`	Store or display the report and its source references
`failed`	Show the error and offer an intentional retry
`cancelled`	Stop waiting and show that the run was cancelled

A browser disconnect or local polling timeout does not prove the remote task failed. Check the existing task before creating a replacement. A replacement is a new research run and can incur another charge. Creating a task holds its mode price against your balance. Handle 402 (not enough available balance, with the required and available amounts in the message) by prompting a top-up, and 503 (Billing temporarily unavailable, no task created) by retrying with backoff. See billing and credit holds.

Choose polling or webhooks

For an initial integration, the SDK’s wait helper handles polling. Set its timeout to suit your chosen mode: about 15 minutes for fast, 30 for standard, 60 for heavy and 120 for max (see research modes). For a server application, webhooks let a worker process completion without keeping a page request open. When accepting a webhook, verify its signature against the original body, enforce timestamp freshness, and make processing safe to repeat. Fetch task status when reconciling missing notifications; cancellation does not trigger a completion webhook.

Show the evidence with the result

Preserve the report’s citations and source URLs in the rendered output. Give users a way to open sources and distinguish a reported fact from an estimate or unresolved gap. Before presenting a financial table, check the period, currency and entity. Before presenting a scientific comparison, check the study population, intervention, comparator and outcome. A source reference makes review possible; it does not replace that review.

Test one task before scaling it

Run representative examples and inspect the output that your application actually displays, including tables, citations and any structured fields. Check whether the user can finish the intended job and which edits they still make. Choose how to repeat the job once the output is useful:

What repeats?	Use
The instructions and output format, with different user inputs	A versioned workflow
Many independent queries with the same mode and search settings	A batch
A single investigation with its own files or review checkpoints	An individual DeepResearch task

Pin a workflow version to retain its configuration. Fresh sources and research execution can still produce different results between runs.

Research configuration

Sources, structured output, files and task management.

Human review

Let users review the plan or sources before writing.

Start here

APIs

Finance workflows

Sciences workflows

Build and connect

Comparisons

Research in your application

Define the job before the prompt

Keep the task outside the page request

Choose polling or webhooks

Show the evidence with the result

Test one task before scaling it

Research configuration

Human review

​Define the job before the prompt

​Keep the task outside the page request

​Choose polling or webhooks

​Show the evidence with the result

​Test one task before scaling it

Research configuration

Human review

Define the job before the prompt

Keep the task outside the page request

Choose polling or webhooks

Show the evidence with the result

Test one task before scaling it