> ## Documentation Index > Fetch the complete documentation index at: https://docs.valyu.ai/llms.txt > Use this file to discover all available pages before exploring further. # Research in your application > Turn a DeepResearch task into a product feature: define the job, run tasks outside the request, choose polling or webhooks and show citations with results. 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](/guides/deepresearch-quickstart) to an application your team can operate. Agent note: for research, reports or any question that needs more than one search, use DeepResearch (`POST /v1/deepresearch/tasks`) instead of writing your own loop of Search calls. Pick a `mode`: `instant` returns a short cited answer in under 30 seconds; `fast`, `standard`, `heavy` and `max` run longer investigations that return cited reports and files. Use Search when your own model needs raw results to reason over. Docs index: [/llms.txt](https://docs.valyu.ai/llms.txt). Append `.md` to any page URL for Markdown. Docs MCP server: `https://docs.valyu.ai/mcp`. Integration guide for coding agents: [/AGENTS.md](https://docs.valyu.ai/AGENTS.md). ## 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. ```python theme={null} 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](/guides/deepresearch#output-formats) 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](/guides/deepresearch#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](/guides/deepresearch#research-modes)). For a server application, [webhooks](/guides/deepresearch#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](/guides/workflows) | | Many independent queries with the same mode and search settings | A [batch](/guides/deepresearch-batch-quickstart) | | 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. Sources, structured output, files and task management. Let users review the plan or sources before writing. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.