Asynchronous deep research using the Valyu Python SDK
The DeepResearch API performs comprehensive research by searching multiple sources, analyzing content, and generating detailed reports. Tasks run in the background, enabling thorough multi-step research.
For conceptual overview, search configuration details, and best practices, see the DeepResearch Guide. This page focuses on Python SDK method reference.
from valyu import Valyuvalyu = Valyu()# Create a research tasktask = valyu.deepresearch.create( query="What are the key differences between RAG and fine-tuning for LLMs?", mode="standard")if task.success: print(f"Task created: {task.deepresearch_id}") # Wait for completion with progress updates result = valyu.deepresearch.wait( task.deepresearch_id, on_progress=lambda s: print(f"Status: {s.status}") ) if result.status == "completed": print(result.output) print(f"Cost: ${result.cost}")
Balanced research, deeper insights without long wait times
~10-20 minutes
heavy
In-depth, long-running research tasks, complex analysis
Up to ~90 minutes
max
Exhaustive research with maximum quality and fact verification
Up to ~180 minutes
The lite mode is deprecated and maps to standard.
# Use fast mode for quick lookupstask = valyu.deepresearch.create( query="What is quantum computing?", mode="fast")# Use heavy mode for complex researchtask = valyu.deepresearch.create( query="Analyze the competitive landscape of cloud computing in 2024", mode="heavy")# Use max mode for exhaustive researchtask = valyu.deepresearch.create( query="Comprehensive analysis of AI safety research with fact verification", mode="max")
Request both markdown and a downloadable PDF report:
task = valyu.deepresearch.create( query="Write a report on renewable energy trends", output_formats=["markdown", "pdf"])result = valyu.deepresearch.wait(task.deepresearch_id)if result.pdf_url: print(f"PDF available at: {result.pdf_url}")
Get research results in TOON format for structured, machine-readable deliverables. TOON format requires a JSON schema and cannot be mixed with markdown/pdf.
The tools parameter controls which optional capabilities the research agent can use during a task. All tools are off by default and must be explicitly enabled.
Tool
Description
code_execution
Run Python code in a sandboxed environment. Required for XLSX/PPTX/DOCX deliverable generation.
screenshots
Capture visual screenshots of web pages. The agent decides when screenshots add value (charts, dashboards, infographics).
You enable tools — the agent decides when to use them. For example, enabling screenshots does not screenshot every page; the agent selects pages where visual context is valuable.
When screenshots is enabled, captured screenshots appear in the images array with image_type: "screenshot":
result = valyu.deepresearch.wait(task.deepresearch_id)for image in result.images or []: if image.image_type == "screenshot": print(f"Screenshot of {image.source_url}: {image.image_url}")
Generate additional file outputs alongside the research report. Deliverables allow you to extract structured data or create formatted documents (CSV, Excel, PowerPoint, Word, PDF) from the research.
task = valyu.deepresearch.create( query="Research the top 20 AI companies in 2024", deliverables=[ "CSV file with company names, founding year, and funding", "PowerPoint presentation with 5 slides summarizing key findings" ])result = valyu.deepresearch.wait(task.deepresearch_id)if result.deliverables: for deliverable in result.deliverables: if deliverable.status == "completed": print(f"✅ {deliverable.title}") print(f" Download: {deliverable.url}") if deliverable.row_count: print(f" Rows: {deliverable.row_count}")
Include specific URLs to analyze alongside web research:
task = valyu.deepresearch.create( query="Compare the approaches described in these articles", urls=[ "https://example.com/article-1", "https://example.com/article-2" ])
Retrieve authenticated assets (images, charts, deliverables, PDFs) from completed tasks. Supports both API key authentication (default) and token-based authentication.
# Using API key (default)asset_data = valyu.deepresearch.get_assets(task_id, asset_id)if asset_data: # asset_data is bytes containing the binary data with open("output.png", "wb") as f: f.write(asset_data)# Using tokenasset_data = valyu.deepresearch.get_assets( task_id, asset_id, token="asset-access-token")
Returns:bytes - Binary asset data, or None if the asset is not found.
Add instructions to refine or adjust the scope of a running task to guide the research and report generation process.
Follow-up instructions can only be added before the writing phase starts. Once research completes and the writing phase begins, new instructions are rejected.
# Add first instructionresponse = valyu.deepresearch.update( task_id, instruction="Focus more on peer-reviewed sources from 2024")if response.success: print("Instruction added")# Add another instructionresponse = valyu.deepresearch.update( task_id, instruction="Include a comparison table of major providers")
Get notified when research completes instead of polling. See the DeepResearch Guide for complete webhook documentation including signature verification and retry behavior.
task = valyu.deepresearch.create( query="Research market trends in AI", webhook_url="https://your-app.com/webhooks/deepresearch")# IMPORTANT: Save the secret immediately - it's only returned oncewebhook_secret = task.webhook_secret
The webhook_secret is only returned once. Store it securely—you cannot retrieve it later.
