Day 3 of 30 Days of Search.
A research task does not always end with a report. Your app might need JSON. An analyst might need an Excel workbook. A team meeting might need slides.
Searching is very common and popular. However there's a flow that makes use multi-step searches and analysis in such a way that gives you better & deeper research-analyst-type results. It's called DeepResearch.
With deep research, you can choose a research depth, an output format, the files to generate, and the tools the agent can use. You can also for human review or run a reusable workflow.
By the end of this guide, you will know how to:
The CLI examples in this article use Valyu CLI 1.2.2. The Python examples use valyu 2.12.2. Mode names, prices, and feature details below were checked against the current documentation.
A Search API returns results for your application to use. DeepResearch takes responsibility for the broader investigation: planning searches, reading sources, following up on gaps, and writing a cited result.
The conceptual flow looks like this:
Valyu can search the web alongside academic, financial, medical, patent, and other specialised sources. The sources available to a particular run depend on your account access and search configuration.
Tasks are asynchronous: create a task, save its ID, then wait or receive a webhook notification. If you need a quick synchronous answer rather than an investigation, consider the Answer API.
Keep three decisions separate:
| Decision | What you choose |
|---|---|
| Research mode | How much research budget to allocate: fast ,standard ,heavy , ormax |
| Report output | Markdown, PDF, schema-based JSON, or schema-based TOON |
| Deliverables | Additional files such as a spreadsheet, document, or slide deck |
PDF and JSON are output choices, not research modes. A longer run also does not guarantee that every finding is correct. Read the cited evidence before relying on important conclusions.
You need a Valyu account with available free credits. Get access at platform.valyu.ai.
Install the CLI:
npm install -g @valyu/cli@1.2.2
valyu login
valyu --version
valyu login opens a browser authentication flow. Standalone installation options are in the CLI documentation.
Use fast when you need a limited research pass rather than a broad investigation. For example, compare two approaches for one specific application:
valyu deepresearch create \
"Compare RAG and fine-tuning for a developer-support assistant. Focus on updating knowledge and citing sources." \
--mode fast \
--output-format markdown
Creation returns a task ID. Paste it into the variable below:
TASK_ID="paste-the-returned-task-id"
valyu deepresearch watch "$TASK_ID"
Completed report on Valyu platform
Use standard mode when you need a wider comparison with practical constraints:
valyu deepresearch create \
"Compare RAG and fine-tuning for a developer-support assistant. Cover freshness, citations, maintenance, and evaluation." \
--mode standard \
--research-strategy "Prioritise official documentation and published evaluations. Separate evidence from recommendations." \
--report-format "Write an engineering brief with a comparison table, recommendations, limitations, and citations." \
--output-format markdown
The distinction between the two instruction flags is useful:
--research-strategy guides the investigation: what to examine and which evidence to prioritise.--report-format guides the result: its structure, style, and length.
The typical runtime is 10 to 20 minutes. A well-scoped question matters more than asking for a long report.
Use heavy when the work involves conflicting evidence, multiple approaches, or a detailed research review:
valyu deepresearch create \
"Evaluate RAG, fine-tuning, and hybrid approaches for developer support. Compare published evaluations, failure cases, and operational trade-offs." \
--mode heavy \
--research-strategy "Compare evaluation methods and their limitations. Flag results that are not directly comparable." \
--output-format markdown
It takes approximately 90 minutes** for heavy mode.
There is also max mode for exhaustive research. It has a higher base price and requires at least $15 in available credits. Check the task scope before choosing it.
| Mode | Listed base price per task | Runtime listed on the pricing page | Useful starting point |
|---|---|---|---|
fast |
$0.10 | About 5 minutes | A focused lookup or lightweight comparison |
standard |
$0.50 | About 10 to 20 minutes | A balanced research brief |
heavy |
$2.50 | Up to about 90 minutes | Complex analysis with competing evidence |
max |
$15.00 | Up to about 180 minutes | An exhaustive investigation |
The API defaults to Markdown. Request both formats explicitly when you want text for your app and a PDF for readers:
valyu deepresearch create \
"Compare RAG and fine-tuning for developer support. Write an executive summary with an evidence table and citations." \
--mode standard \
--output-format markdown \
--output-format pdf
After the task completes, its response includes the report in output and, when generated successfully, the PDF link in pdf_url.
PDF changes how you distribute the report. It does not select a deeper research mode. The CLI's --no-pdf flag and default format behaviour are separate from the API's Markdown default; explicit formats avoid that ambiguity.
Example of a deepresearch report with PDF output
Use a JSON schema when your next step is a dashboard, database, or another agent. This avoids an extra prose-to-data extraction step.
This example runs DeepResearch, not the separate Answer API:
valyu deepresearch create \
"Compare RAG and fine-tuning for developer support. Return each approach, its best fit, its limitations, and supporting source URLs." \
--mode standard \
--structured '{
"type": "object",
"properties": {
"approaches": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"best_fit": { "type": "string" },
"limitations": { "type": "string" },
"source_urls": {
"type": "array",
"items": { "type": "string" }
}
},
"required": ["name", "best_fit", "limitations", "source_urls"]
}
}
},
"required": ["approaches"]
}'
For larger schemas, save the JSON to a file and use --structured-file schema.json.
Do not combine a schema with Markdown or PDF report output. Structured output is an alternative report representation. Validate the returned data and check its evidence before using it for decisions.
DeepResearch also supports TOON, a token-oriented structured representation. It requires a schema.
In the CLI, use --structured-file schema.json --output-format toon. Use JSON when your existing application expects JSON; TOON is an optional representation, not another file-deliverable type.
A report format controls the main response. Deliverables are additional files generated from the research, each with its own type, description, status, and download URL.
You can specify all five of these file types:
| Deliverable type | File format | Example use |
|---|---|---|
csv |
CSV ( .csv ) |
A research table to import into another system |
xlsx |
Excel workbook ( .xlsx ) |
A comparison workbook with evidence columns |
docx |
Word document ( .docx ) |
An editable research brief |
pptx |
PowerPoint presentation ( .pptx ) |
A slide deck for a team review |
pdf |
PDF document ( .pdf ) |
A separately specified formatted document |
The task API accepts up to 10 deliverables. Excel, Word, and PowerPoint deliverables require code execution to be enabled. The basic PDF report requested through output_formats is separate from the deliverables list.
from valyu import Valyu
client = Valyu()
task = client.deepresearch.create(
query="Compare RAG and fine-tuning for a developer-support assistant. "
"Cover freshness, citations, maintenance, and evaluation.",
mode="heavy",
output_formats=["markdown"],
tools={"code_execution": True, "charts": True},
deliverables=[
{
"type": "xlsx",
"description": "Comparison workbook with an evidence URL for each row.",
"columns": ["Approach", "Best fit", "Limitations", "Source URL"],
},
{
"type": "pptx",
"description": "Six-slide engineering review with recommendations "
"and a sources slide.",
"slides": 6,
},
],
)
if not task.success or not task.deepresearch_id:
raise RuntimeError("Could not create the research task.")
print("Save this task ID:", task.deepresearch_id, flush=True)
result = client.deepresearch.wait(
task.deepresearch_id,
poll_interval=20,
max_wait_time=7200,
)
if not result.success or result.status != "completed":
raise RuntimeError("Research did not complete successfully. Check the task status.")
print(result.output)
print("Reported total cost:", result.cost)
for item in result.deliverables or []:
if item.status == "completed":
print(item.type, item.title, item.url)
else:
print(item.type, "deliverable status:", item.status)
The waiting options use seconds in Python. 7200 is a two-hour polling budget, not a guaranteed completion time. If waiting stops, keep the task ID and inspect that existing run rather than creating it again.
Check each file's status, not only the report status. Deliverable download URLs are signed and expire; download files you need to keep.
The optional tools are off by default for a freeform task. Enabling a tool makes it available; the agent decides whether to use it.
| Tool | What it enables | Important detail |
|---|---|---|
code_execution |
Run Python calculations and generate files in a sandbox | No network access; required for XLSX, DOCX, and PPTX deliverables |
screenshots |
Capture web pages, including charts and dashboards | Captures appear in the task's images ; usage is chargeable |
browser_use |
Navigate pages through autonomous browser sessions | Enable it when the investigation needs browser interaction |
charts |
Generate charts for the report | Generated charts appear in images ; no chart surcharge |
For a terminal-based run with code execution, screenshots, and browser use:
valyu deepresearch create \
"Compare publicly listed pricing for developer-support tools. Capture relevant pricing pages and distinguish monthly from annual billing." \
--mode standard \
--code-execution \
--screenshots \
--browser-use \
--output-format markdown
The Python example above enables charts through tools={"code_execution": True, "charts": True}. The API also accepts per-tool max_calls limits. You can lower the documented limits, not raise them.
A screenshot records a page; it does not prove a pricing claim is complete or current. A calculation is only as good as its inputs. Keep the source links and assumptions with the result.
A deepresearch report showing research activity
Human-in-the-loop, or HITL, adds optional checkpoints. You can enable any combination of four:
| Checkpoint | What the reviewer does |
|---|---|
planning_questions |
Answer clarifying questions before research begins |
plan_review |
Approve the research plan or request changes |
source_review |
Include or exclude source domains after research |
outline_review |
Review the report outline before writing |
The CLI uses hyphenated checkpoint names. Start an interactive session with plan and source review:
valyu deepresearch create \
"Compare RAG and fine-tuning for developer support, focusing on evidence quality and deployment constraints." \
--mode heavy \
--hitl plan-review,source-review \
--output-format markdown \
--watch
Run this in an interactive terminal so watch can prompt for your decisions. In an application, use the SDK's interaction callback or the task's respond endpoint to collect and submit a person's response.
At a checkpoint, status becomes awaiting_input. The documentation says an unanswered checkpoint becomes d after five minutes, with state saved; you can respond later to resume. Human response time adds to the overall runtime.
HITL is available for individual tasks, not batch requests. It is useful when scope, source selection, or the report structure needs review before the work proceeds.
If you produce the same kind of brief repeatedly, a workflow gives you a reusable, versioned starting point.
A workflow can bundle a prompt with typed variables, a research strategy, report instructions, output formats, deliverables, tools, and a recommended mode. You supply the changing inputs, such as a company or sector.
Valyu provides curated workflows, and organisations can create private ones. Examples of these workflows include company profiles, diligence briefs, earnings research, and competitor scans. Workflows are currently in beta.
The workflow runs through the normal DeepResearch lifecycle. It is not a separate synchronous API.
Curated workflows on the platform
Using the Python environment above, save this as preview_workflow.py and run python preview_workflow.py:
from valyu import Valyu
client = Valyu()
listing = client.workflows.list(scope="valyu", vertical="investment-banking")
if not listing.success:
raise RuntimeError("Could not list workflows.")
for workflow in listing.workflows or []:
print(workflow.slug, workflow.title)
profile = client.workflows.get("ib-company-profile")
if not profile.success or not profile.workflow or profile.workflow.version is None:
raise RuntimeError("Could not inspect the workflow.")
print("Workflow inputs:", profile.workflow.variables)
preview = client.workflows.preview(
"ib-company-profile",
workflow_params={"company": "NVIDIA (NVDA)"},
workflow_version=profile.workflow.version,
)
if not preview.success or not preview.resolved:
raise RuntimeError("Could not preview the workflow.")
print("Resolved research request:", preview.resolved.input)
print("Mode:", preview.resolved.mode)
print("Deliverables:", preview.resolved.deliverables)
print("Estimated credits:", preview.estimated_credits)
A preview resolves the template without starting research or spending research credits. Inspect the workflow's variables: a different template can require different parameter names.
When you are ready to start the billed task, add this to the same file:
task = client.deepresearch.create(
workflow_id="ib-company-profile",
workflow_params={"company": "NVIDIA (NVDA)"},
workflow_version=profile.workflow.version,
)
if not task.success or not task.deepresearch_id:
raise RuntimeError("Could not start the workflow.")
print("Workflow task ID:", task.deepresearch_id)
Watch that ID with valyu deepresearch watch using the same account, or wait through the SDK.
Do not send query, research_strategy, or report_format alongside workflow_id. The template supplies those fields. Pinning workflow_version keeps later template changes from silently changing the process, although live sources can still produce different results.
You can override options such as mode, deliverables, or search filters per run. Tools merge with the template's settings: explicitly disable a template-enabled tool if you do not want it.
Workflow preview with filled variables in the platform UI
Note: Give your agents DeepResearch access with a key from platform.valyu.ai. $20 in free credits; check the current offer before signing up.
Yes. Use --output-format markdown --output-format pdf in the CLI, or output_formats=["markdown", "pdf"] in Python. A schema cannot be combined with those report formats.
CSV (csv), Excel ( xlsx), Word ( docx), PowerPoint ( pptx), and PDF ( pdf). XLSX, DOCX, and PPTX require code execution. Deliverables have their own statuses and download links.
Yes, when you enable those tools. Code execution runs Python in a sandbox without network access. Browser use is a separate capability. Screenshots and charts are also optional tools.
Yes. Enable plan_review, or plan-review in the CLI's --hitl list. The task waits for your response. You can also enable clarifying questions, source review, and outline review.
No. A workflow is a template for new research runs. A preview resolves its inputs without executing research; running it creates a new DeepResearch task with normal billing.
No. A larger research budget can support a broader investigation. It does not replace checking citations, comparing sources, and reviewing the assumptions behind calculations.