> ## 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.

# Python SDK: DeepResearch

> Create DeepResearch tasks from Python, pick a mode from instant to max, wait for completion or use webhooks, and get cited reports and structured output.

Run a multi-step investigation and retrieve a cited report or structured output. Create a task, retain its ID, then wait for completion or receive a webhook.

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).

> [!NOTE]
>
> For the conceptual overview, search configuration, and best practices, see the [DeepResearch Guide](https://docs.valyu.ai/guides/deepresearch.md). This page is the Python SDK method reference.

## Basic usage

```python theme={null}
from valyu import Valyu

valyu = Valyu()

task = valyu.deepresearch.create(
    query="What are the key differences between RAG and fine-tuning for LLMs?",
    mode="standard",
)

if task.success:
    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

Set `mode` to `instant` (8 credits per task, a short cited answer in under 30 seconds), `fast` (25 credits per task), `standard` (100 credits, the default), `heavy` (500) or `max` (2,500). Tool and deliverable charges can apply; see [pricing](https://docs.valyu.ai/pricing.md) and the [DeepResearch guide](https://docs.valyu.ai/guides/deepresearch.md) for mode selection.

Creating a task holds its mode price against your balance, so you need at least that amount available (for example 2,500 credits for `max`). See [billing and credit holds](https://docs.valyu.ai/guides/deepresearch.md#billing-and-credit-holds) for the `402` and `503` responses.

## Output formats

```python theme={null}
# Markdown (default), optionally with a downloadable PDF
task = valyu.deepresearch.create(query="...", output_formats=["markdown", "pdf"])

# Structured JSON - pass a single JSON Schema instead of markdown/pdf
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"},
            }}},
            "market_summary": {"type": "string"},
        },
        "required": ["competitors", "market_summary"],
    }],
)
```

> [!WARNING]
>
> You cannot mix a JSON Schema with `markdown`/`pdf`. [TOON format](https://github.com/toon-format/toon) also requires a JSON schema.

## Waiting for completion

```python theme={null}
result = valyu.deepresearch.wait(
    task.deepresearch_id,
    poll_interval=5,      # seconds between status checks
    max_wait_time=900,    # timeout in seconds (raise for heavy/max)
    on_progress=lambda s: print(s.status),
)
```

In production, prefer webhooks over polling. The `webhook_secret` is returned **only once** on create - store it immediately:

```python theme={null}
task = valyu.deepresearch.create(
    query="Research market trends in AI",
    webhook_url="https://your-app.com/webhooks/deepresearch",
)
webhook_secret = task.webhook_secret  # store securely - not retrievable later
```

| Mode | Poll interval | Timeout |
| - | - | - |
| `fast` | 2-5s | 15 min |
| `standard` | 5-10s | 30 min |
| `heavy` | 10-30s | 60 min |
| `max` | 30-60s | 120 min |

## Newer response fields

Use valyu-py 2.13.7 or later to read `cost_detail`, `cost_credits`, `research_mode`, `research_output_formats`, `error_code` and `pending_deliverables`. Prefer them to `cost_breakdown`, `mode`, `output_formats` and `error`. See [the newer response fields](https://docs.valyu.ai/guides/deepresearch.md#read-the-newer-response-fields).

## Reference

> [accordion] create() parameters
>
> **`query`** (str, required) - research query or task description.
>
> | Parameter | Type | Description | Default |
> | - | - | - | - |
> | `mode` | `"fast"` \| `"standard"` \| `"heavy"` \| `"max"` | Research mode | `"standard"` |
> | `output_formats` | list | `["markdown"]`, `["markdown", "pdf"]`, or a single JSON schema | `["markdown"]` |
> | `research_strategy` | str | Natural-language strategy to guide research | None |
> | `report_format` | str | Natural-language output format instructions (highest priority) | None |
> | `search` | dict | Search config (filters, date range). See the [DeepResearch Guide](https://docs.valyu.ai/guides/deepresearch.md#search-configuration) | None |
> | `urls` | list\[str] | URLs to analyze (max 50, first 10 free) | None |
> | `files` | list\[dict] | File attachments (max 10) | None |
> | `deliverables` | list\[str \| Deliverable] | Additional file outputs (max 10) | None |
> | `mcp_servers` | list\[dict] | MCP server configs (max 5) | None |
> | `tools` | dict \| DeepResearchTools | Optional agent tools, each off by default | 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 \| AlertEmailConfig | Email for completion notifications | None |
> | `hitl` | dict \| HitlConfig | Human-in-the-loop checkpoints. See [HITL](https://docs.valyu.ai/sdk/python-sdk/deepresearch-hitl.md). Not available for batch | None |

> [accordion] Tools (code execution, screenshots, browser, charts)
>
> All tools are **off by default**. You enable them; the agent decides when to use them. Each accepts a boolean or `{"enabled": bool, "max_calls": int}` (`max_calls` can only be lowered from the system default).
>
> | Tool | Description | Default max\_calls |
> | - | - | - |
> | `code_execution` | Run sandboxed Python (no network). Required for XLSX/PPTX/DOCX deliverables | 10 |
> | `screenshots` | Capture page screenshots (charts, dashboards) | 15 |
> | `browser_use` | Autonomous browser sessions | 5 |
> | `charts` | Generate charts embedded in the report. No additional chart charge | - |
>
> ```python theme={null}
> task = valyu.deepresearch.create(
>     query="Analyse Tesla's Q3 earnings. Screenshot revenue charts and calculate YoY growth.",
>     mode="heavy",
>     tools={
>         "code_execution": {"enabled": True},
>         "screenshots": {"enabled": True, "max_calls": 5},
>         "charts": True,
>     },
> )
> ```
>
> Generated screenshots and charts appear in `result.images` with `image_type` of `"screenshot"` or `"chart"`. See [Pricing](https://docs.valyu.ai/pricing.md#optional-charges) for surcharges. Code execution is Python-only with a 30s default timeout (5-60s); screenshots are capped at 15 per task and 5 MB each.

> [accordion] Deliverables (CSV, Excel, PowerPoint, Word, PDF)
>
> Generate formatted documents from the research (max 10 per task, produced after research completes). Use simple strings or the typed `Deliverable`:
>
> ```python theme={null}
> from valyu import Deliverable
>
> task = valyu.deepresearch.create(
>     query="Research the top 20 AI companies in 2024",
>     tools={"code_execution": True},
>     deliverables=[
>         "CSV file with company names, founding year, and funding",
>         Deliverable(type="pptx", description="Executive summary", slides=10, template="modern"),
>     ],
> )
>
> if not task.success or not task.deepresearch_id:
>     raise RuntimeError(task.error)
>
> for d in valyu.deepresearch.wait(task.deepresearch_id).deliverables or []:
>     if d.status == "completed":
>         print(d.title, d.url)
> ```
>
> | Type | Optional fields |
> | - | - |
> | `csv` | `columns`, `include_headers` |
> | `xlsx` | `columns`, `include_headers`, `sheet_name` |
> | `pptx` | `slides`, `template` |
> | `docx` | `template` |
> | `pdf` | `template` |
>
> Each `DeliverableResult` has `id`, `type`, `status`, `title`, `url` (token-signed, expires), `row_count`/`column_count` (CSV/Excel), and `error` if failed.

> [accordion] File attachments and URLs
>
> ```python theme={null}
> import base64
>
> 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",
>     }],
>     urls=["https://example.com/article-1"],
> )
> ```
>
> Supported file types: PDFs, images (PNG, JPEG, WebP), and documents.

> [accordion] 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
>     output_type: str  # "markdown" | "json" | "toon"
>     output: str | dict
>     sources: list[DeepResearchSource]
>     cost: float
>     cost_breakdown: DeepResearchCostBreakdown | None
>     tools: DeepResearchTools | None
>     created_at: str
>     completed_at: str | None
>     pdf_url: str | None
>     images: list[ImageMetadata]
>     deliverables: list[DeliverableResult]
>     batch_id: str | None
>     batch_task_id: str | None
>     error: str | None
>
> class DeepResearchSource:
>     title: str
>     url: str
>     snippet: str
>     source: str  # web, pubmed, arxiv, etc.
>     word_count: int
>     doi: str | None
>     fragment: str | None  # append to url for a deep-link to the cited passage
> ```
>
> `cost` is the total price (base mode + tool surcharges); `cost_breakdown` itemizes it.

> [accordion] Task management
>
> ```python theme={null}
> valyu.deepresearch.status(task_id)                 # current status + progress
> valyu.deepresearch.update(task_id, instruction=...) # add follow-up instructions (before writing phase)
> valyu.deepresearch.respond(task_id, interaction_id=..., response=...)  # answer a HITL checkpoint
> valyu.deepresearch.cancel(task_id)
> valyu.deepresearch.delete(task_id)
> valyu.deepresearch.list(limit=50)
> valyu.deepresearch.toggle_public(task_id, is_public=True)
>
> # Download authenticated assets (images, charts, deliverables, PDFs) as bytes
> data = valyu.deepresearch.get_assets(task_id, asset_id)
> if data:
>     open("output.png", "wb").write(data)
> ```
>
> > [!WARNING]
> >
> > Follow-up instructions via `update()` are only accepted **before the writing phase starts**.

## See also

> [card] [DeepResearch Guide](https://docs.valyu.ai/guides/deepresearch.md)
>
> Search config, webhooks, and use cases

> [card] [Batch Processing](https://docs.valyu.ai/sdk/python-sdk/deepresearch-batch.md)
>
> Run many research tasks in parallel

> [card] [Human-in-the-loop](https://docs.valyu.ai/sdk/python-sdk/deepresearch-hitl.md)
>
> Pause at checkpoints to guide the agent

> [card] [API Reference](https://docs.valyu.ai/api-reference/endpoint/deepresearch-create.md)
>
> REST endpoint documentation


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.