> ## 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.
# DeepResearch API
> 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](/guides/deepresearch). This page focuses on Python SDK method reference.
## Basic Usage
```python theme={null}
from valyu import Valyu
valyu = Valyu()
# Create a research task
task = 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}")
```
## Research Modes
DeepResearch offers four modes optimized for different use cases:
| Mode | Best For | Typical Completion Time |
| ---------- | -------------------------------------------------------------- | ----------------------- |
| `fast` | Quick answers, lightweight research, simple lookups | \~5 minutes |
| `standard` | 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`.
```python theme={null}
# Use fast mode for quick lookups
task = valyu.deepresearch.create(
query="What is quantum computing?",
mode="fast"
)
# Use heavy mode for complex research
task = valyu.deepresearch.create(
query="Analyze the competitive landscape of cloud computing in 2024",
mode="heavy"
)
# Use max mode for exhaustive research
task = valyu.deepresearch.create(
query="Comprehensive analysis of AI safety research with fact verification",
mode="max"
)
```
## Parameters
### Query (Required)
| Parameter | Type | Description |
| --------- | ---- | ---------------------------------- |
| `query` | str | Research query or task description |
### Options (Optional)
| Parameter | Type | Description | Default |
| ------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
| `mode` | `"fast"` \| `"standard"` \| `"heavy"` \| `"max"` | Research mode. The `lite` mode is deprecated and maps to `standard`. | `"standard"` |
| `output_formats` | list | Output formats (see below) | `["markdown"]` |
| `strategy` | str | **Deprecated.** Use `research_strategy` instead | None |
| `research_strategy` | str | Natural language strategy to guide the research phase | None |
| `report_format` | str | Natural language instructions for output format (highest priority) | None |
| `search` | dict | Search configuration (filters, date range) | None |
| `urls` | `list[str]` | URLs to analyze (max 10) | None |
| `files` | `list[dict]` | File attachments (max 10) | None |
| `deliverables` | `list[str \| Deliverable]` | Additional file outputs to generate (max 10) | None |
| `mcp_servers` | `list[dict]` | MCP server configurations (max 5) | None |
| `tools` | `dict` or `DeepResearchTools` | Optional agent tools to enable. See [Tools](#tools) below. | `None` |
| `previous_reports` | `list[str]` | Previous task IDs for context (max 3) | None |
| `webhook_url` | str | HTTPS URL for completion notification | None |
| `metadata` | dict | Custom metadata for tracking | None |
| `alert_email` | `str` or `AlertEmailConfig` | Email for completion notifications. Can be a string or `{"email": "...", "custom_url": "https://.../{id}"}` with `{id}` placeholder for the task ID. | `None` |
| `hitl` | `dict` or `HitlConfig` | Human-in-the-loop configuration. Enable checkpoints that pause at key decision points. See [HITL Guide](/guides/deepresearch-hitl). Not available for batch. | `None` |
## Output Formats
### Markdown (Default)
```python theme={null}
task = valyu.deepresearch.create(
query="Explain quantum computing advancements in 2024",
output_formats=["markdown"]
)
```
### Markdown + PDF
Request both markdown and a downloadable PDF report:
```python theme={null}
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}")
```
### Structured JSON
Get research results in a custom schema using [JSON Schema](https://json-schema.org/understanding-json-schema) specification:
```python theme={null}
task = valyu.deepresearch.create(
query="Research competitor pricing in the SaaS market",
output_formats=[{
"type": "object",
"properties": {
"competitors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {"type": "string"},
"pricing_model": {"type": "string"},
"price_range": {"type": "string"},
"key_features": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["name", "pricing_model"]
}
},
"market_summary": {"type": "string"},
"recommendations": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["competitors", "market_summary"]
}]
)
result = valyu.deepresearch.wait(task.deepresearch_id)
if result.output_type == "json":
data = result.output
for competitor in data["competitors"]:
print(f"{competitor['name']}: {competitor['pricing_model']}")
```
### TOON Format
Get research results in [TOON format](https://github.com/toon-format/toon) for structured, machine-readable deliverables. TOON format requires a JSON schema and cannot be mixed with markdown/pdf.
```python theme={null}
task = valyu.deepresearch.create(
query="Research competitor pricing in the SaaS market",
output_formats=[{
"type": "object",
"properties": {
"competitors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {"type": "string"},
"pricing_model": {"type": "string"}
}
}
}
},
"required": ["competitors"]
}]
)
```
You cannot mix JSON Schema with markdown/pdf formats. Use one or the other. TOON format requires a JSON schema.
The schema must be a valid [JSON Schema](https://json-schema.org/understanding-json-schema). Use `type`, `properties`, `required`, `items`, and other standard JSON Schema keywords.
## Search Configuration
The `search` parameter controls which data sources are queried. See the [DeepResearch Guide](/guides/deepresearch#search-configuration) for complete documentation of all search options.
```python theme={null}
task = valyu.deepresearch.create(
query="Research AI trends",
search={
"search_type": "proprietary",
"included_sources": ["academic", "finance"],
"start_date": "2024-01-01",
"end_date": "2024-12-31",
"country_code": "US" # Filter web results by country
}
)
```
### Search Parameters
| Parameter | Type | Description |
| ------------------ | ------------------------------------- | --------------------------------------------------------------------------------- |
| `search_type` | `"all"` \| `"web"` \| `"proprietary"` | Which search systems to query |
| `included_sources` | list\[str] | Only search these source types |
| `excluded_sources` | list\[str] | Exclude these source types |
| `start_date` | str | ISO date (`YYYY-MM-DD`) for minimum date |
| `end_date` | str | ISO date (`YYYY-MM-DD`) for maximum date |
| `category` | str | Filter by category (source-dependent) |
| `country_code` | str | ISO 3166-1 alpha-2 code (e.g., `"US"`, `"GB"`) for location-filtered web searches |
Available source types: `web`, `academic`, `finance`, `patent`, `transportation`, `politics`, `legal`
## Tools
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). |
| `charts` | Generate charts and graphs embedded in the final report. Free, no per-call surcharge. |
See [Pricing](/pricing#tool-surcharges) for per-tool surcharge details.
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.
### Enabling tools
```python theme={null}
task = valyu.deepresearch.create(
query="Analyse Tesla's Q3 2026 earnings. Screenshot their investor relations page and any revenue charts. Calculate YoY revenue growth rates and operating margins.",
mode="heavy",
tools={
"code_execution": True,
"screenshots": True,
"charts": True,
}
)
```
### Screenshots
When `screenshots` is enabled, captured screenshots appear in the `images` array with `image_type: "screenshot"`:
```python theme={null}
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}")
```
Screenshot-specific fields on `ImageMetadata`:
| Field | Type | Description |
| ------------- | ---- | ------------------------------------------------- |
| `source_url` | str | The original web page URL that was screenshotted |
| `captured_at` | int | Unix timestamp (ms) when the screenshot was taken |
**Limits:**
* Max 15 screenshots per task
* Max 5 MB per screenshot
* Images capped at 1280 × 4000 px in reports
### Code execution
When `code_execution` is enabled, the agent can run Python code in a sandboxed environment with no network access.
**Limits:**
* Python only
* 30-second default timeout per execution (5–60s range)
* No internet access
* Text output only via `print()`
### Charts
When `charts` is enabled, the agent can generate charts and graphs to visualize data gathered during research. Charts are rendered server-side and embedded directly in the final report.
```python theme={null}
result = valyu.deepresearch.wait(task.deepresearch_id)
for image in result.images or []:
if image.image_type == "chart":
print(f"{image.chart_type}: {image.image_url}")
```
Chart-specific fields on `ImageMetadata`:
| Field | Type | Description |
| -------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chart_type` | str | One of `line`, `bar`, `area`, `pie`, `doughnut`, `radar`, `scatter`, `horizontalBar`, `heatmap`, `boxplot`, `stackedBar`, `stackedArea`, `histogram`, `waterfall`, `timeline`, `bubble` |
| `x_axis_label` | str | Label for the x-axis |
| `y_axis_label` | str | Label for the y-axis |
| `data_series` | list | Series data the chart was rendered from |
**Notes:**
* Free, no per-call surcharge
* Unlimited charts per task
* The agent decides when a chart adds value to the report
## File Attachments
Analyze documents as part of research:
```python theme={null}
import base64
# Read and encode a PDF
with open("report.pdf", "rb") as f:
pdf_data = base64.b64encode(f.read()).decode()
task = valyu.deepresearch.create(
query="Summarize the key findings and compare with market trends",
mode="heavy",
files=[{
"data": f"data:application/pdf;base64,{pdf_data}",
"filename": "report.pdf",
"mediaType": "application/pdf",
"context": "Q4 2024 financial report" # Optional context
}]
)
```
Supported file types: PDFs, images (PNG, JPEG, WebP), and documents.
## Deliverables
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.
### Simple Deliverables
Use simple strings to describe what you need:
```python theme={null}
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}")
```
### Structured Deliverables
Use the `Deliverable` type for precise control:
```python theme={null}
from valyu import Deliverable
task = valyu.deepresearch.create(
query="Analyze startup funding trends in 2024",
deliverables=[
Deliverable(
type="xlsx",
description="Startup funding data with company details",
columns=["Company", "Funding Amount", "Date", "Investors", "Stage"],
include_headers=True,
sheet_name="Funding Data"
),
Deliverable(
type="pptx",
description="Executive summary presentation",
slides=10,
template="modern"
),
Deliverable(
type="pdf",
description="Detailed analysis report with charts and insights"
)
]
)
result = valyu.deepresearch.wait(task.deepresearch_id)
# Access deliverables
for deliverable in result.deliverables:
print(f"{deliverable.type.upper()}: {deliverable.title}")
print(f"Status: {deliverable.status}")
if deliverable.status == "completed":
print(f"Download: {deliverable.url}")
elif deliverable.status == "failed":
print(f"Error: {deliverable.error}")
```
### Deliverable Types
| Type | Description | Optional Fields |
| ------ | ----------------------- | ------------------------------------------ |
| `csv` | Comma-separated values | `columns`, `include_headers` |
| `xlsx` | Excel spreadsheet | `columns`, `include_headers`, `sheet_name` |
| `pptx` | PowerPoint presentation | `slides`, `template` |
| `docx` | Word document | `template` |
| `pdf` | PDF document | `template` |
### Deliverable Response
```python theme={null}
class DeliverableResult:
id: str
request: str # Original description
type: str # "csv" | "xlsx" | "pptx" | "docx" | "pdf"
status: str # "completed" | "failed"
title: str # Generated filename
url: str # Download URL (token-signed, expires)
s3_key: str
row_count: int | None # For CSV/Excel
column_count: int | None # For CSV/Excel
error: str | None # If failed
created_at: str # ISO 8601 timestamp string
```
You can request up to 10 deliverables per research task. Deliverables are generated after the research completes.
## URL Extraction
Include specific URLs to analyze alongside web research:
```python theme={null}
task = valyu.deepresearch.create(
query="Compare the approaches described in these articles",
urls=[
"https://example.com/article-1",
"https://example.com/article-2"
]
)
```
## Waiting for Completion
### Basic Wait
```python theme={null}
result = valyu.deepresearch.wait(task.deepresearch_id)
if result.status == "completed":
print(result.output)
```
### With Progress Callback
Track research progress in real-time:
```python theme={null}
def on_progress(status):
if status.progress:
pct = (status.progress.current_step / status.progress.total_steps) * 100
print(f"Progress: {pct:.0f}% - Step {status.progress.current_step}/{status.progress.total_steps}")
print(f"Status: {status.status}")
result = valyu.deepresearch.wait(
task.deepresearch_id,
poll_interval=5, # Check every 5 seconds
max_wait_time=900, # Timeout after 15 minutes (standard mode)
on_progress=on_progress
)
```
### Polling Parameters
| Parameter | Type | Description | Default |
| --------------- | -------- | ----------------------------- | ------- |
| `poll_interval` | int | Seconds between status checks | `5` |
| `max_wait_time` | int | Maximum wait time in seconds | `3600` |
| `on_progress` | Callable | Callback for progress updates | None |
## Response Format
```python theme={null}
class DeepResearchStatusResponse:
success: bool
deepresearch_id: str
status: str # "queued" | "running" | "completed" | "failed" | "cancelled" | "awaiting_input" | "paused"
query: str
mode: str # "fast" | "standard" | "heavy" | "max"
output_type: str # "markdown" | "json" | "toon"
output: str | dict # Research output
sources: list[DeepResearchSource] # Sources used
cost: float # Fixed cost for the task
cost_breakdown: DeepResearchCostBreakdown | None # Itemized cost breakdown
tools: DeepResearchTools | None # Resolved tools configuration
created_at: str # ISO 8601 timestamp string
completed_at: str | None # ISO 8601 timestamp string
pdf_url: str | None # PDF download URL
images: list[ImageMetadata] # Generated images
deliverables: list[DeliverableResult] # Generated deliverable files
batch_id: str | None # Batch ID if task belongs to a batch
batch_task_id: str | None # Batch task identifier if task belongs to a batch
error: str | None # Error message if failed
```
### Source Object
```python theme={null}
class DeepResearchSource:
title: str
url: str
snippet: str
source: str # web, pubmed, arxiv, etc.
word_count: int
doi: str | None # For academic papers
```
### Cost
The `cost` field contains the total price for the task (base mode price + any tool surcharges). The `cost_breakdown` field provides an itemized breakdown:
```python theme={null}
if result.cost_breakdown:
print(f"Total: ${result.cost}")
print(f" Base: ${result.cost_breakdown.task}")
if result.cost_breakdown.screenshots:
print(f" Screenshots: ${result.cost_breakdown.screenshots}")
if result.cost_breakdown.code_execution:
print(f" Code execution: ${result.cost_breakdown.code_execution}")
if result.cost_breakdown.deliverables:
print(f" Deliverables: ${result.cost_breakdown.deliverables}")
```
## Task Management
### Check Status
```python theme={null}
status = valyu.deepresearch.status(task_id)
print(f"Status: {status.status}")
if status.progress:
print(f"Step {status.progress.current_step}/{status.progress.total_steps}")
```
### Get Assets
Retrieve authenticated assets (images, charts, deliverables, PDFs) from completed tasks. Supports both API key authentication (default) and token-based authentication.
```python theme={null}
# 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 token
asset_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.
### Toggle Public
## toggle\_public()
Toggle public access for a completed DeepResearch task.
```python theme={null}
result = valyu.deepresearch.toggle_public("dr_abc123", is_public=True)
print(result.public) # True
```
### Parameters
| Parameter | Type | Description | Default |
| ----------- | ------ | -------------------------------------------- | -------- |
| `task_id` | `str` | The DeepResearch task ID | Required |
| `is_public` | `bool` | Whether to make the task publicly accessible | Required |
### Response
| Field | Type | Description |
| ----------------- | ------ | ------------------------------- |
| `success` | `bool` | Whether the operation succeeded |
| `deepresearch_id` | `str` | The task ID |
| `public` | `bool` | Current public status |
| `message` | `str` | Status message |
### Add Follow-up Instructions
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.
```python theme={null}
# Add first instruction
response = valyu.deepresearch.update(
task_id,
instruction="Focus more on peer-reviewed sources from 2024"
)
if response.success:
print("Instruction added")
# Add another instruction
response = valyu.deepresearch.update(
task_id,
instruction="Include a comparison table of major providers"
)
```
### Respond to HITL checkpoint
When a task is in `awaiting_input` or `paused` status, respond to the checkpoint:
```python theme={null}
result = client.deepresearch.respond(
task_id="dr_abc123",
interaction_id=status.interaction.interaction_id,
response={"approved": True},
)
print(result.status) # "running" or "queued"
```
### Cancel a Task
```python theme={null}
response = valyu.deepresearch.cancel(task_id)
if response.success:
print("Task cancelled")
```
### Delete a Task
```python theme={null}
response = valyu.deepresearch.delete(task_id)
if response.success:
print("Task deleted")
```
### List All Tasks
```python theme={null}
tasks = valyu.deepresearch.list(limit=50)
for task in tasks.data:
print(f"{task['query'][:50]}... - {task['status']}")
```
## Webhooks
Get notified when research completes instead of polling. See the [DeepResearch Guide](/guides/deepresearch#webhooks) for complete webhook documentation including signature verification and retry behavior.
```python theme={null}
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 once
webhook_secret = task.webhook_secret
```
The `webhook_secret` is only returned once. Store it securely—you cannot retrieve it later.
## Error Handling
```python theme={null}
task = valyu.deepresearch.create(query="Research query")
if not task.success:
print(f"Failed to create task: {task.error}")
return
try:
result = valyu.deepresearch.wait(
task.deepresearch_id,
max_wait_time=1800 # 30 minutes for standard, use 7200 for heavy
)
if result.status == "completed":
print(result.output)
elif result.status == "failed":
print(f"Research failed: {result.error}")
except TimeoutError:
print("Task timed out - cancelling")
valyu.deepresearch.cancel(task.deepresearch_id)
except ValueError as e:
print(f"Task error: {e}")
```
## Best Practices
See the [DeepResearch Guide](/guides/deepresearch#best-practices) for comprehensive best practices including polling strategies, timeouts, and research quality tips.
| Mode | Recommended Poll Interval | Recommended Timeout |
| ---------- | ------------------------- | ------------------- |
| `fast` | 2-5 seconds | 10 minutes |
| `standard` | 5-10 seconds | 30 minutes |
| `heavy` | 10-30 seconds | 120 minutes |
| `max` | 30-60 seconds | 180 minutes |
```python theme={null}
# Production: use webhooks instead of polling
task = valyu.deepresearch.create(
query="Research query",
webhook_url="https://your-app.com/webhooks"
)
```
## See Also
Complete guide with search config, webhooks, and use cases
Process multiple research tasks in parallel
TypeScript SDK reference
REST API endpoint documentation