DeepResearch Batch API | Python SDK

Run many DeepResearch tasks in parallel under one shared configuration, with progress monitoring.

For the batch lifecycle and best practices, see the Batch Processing Guide. This page is the Python SDK reference. HITL checkpoints are not available for batches - use individual deepresearch.create() tasks for those.

Run a batch of DeepResearch tasks in parallel with the Python SDK.

Open in Cursor

Quick start

create_and_run() creates a batch, adds tasks, and (with wait=True) blocks until everything finishes:

from valyu import Valyu

client = Valyu()

batch = client.batch.create_and_run(
    name="Research Batch",
    mode="standard",
    tasks=[
        {"query": "Research AI trends"},
        {"query": "Analyze market data"},
    ],
    wait=True,
    on_progress=lambda s: print(s.batch.counts.completed, "/", s.batch.counts.total),
)

results = client.batch.list_tasks(batch.batch_id, status="completed", include_output=True)
for t in results.tasks:
    print(t.query, "->", t.output[:200], "cost:", t.cost)

To build a batch incrementally instead, use create() then add_tasks(), and wait_for_completion() to block.

Reference

Methods

Method	Description
`create(name, mode, output_formats, search, webhook_url, metadata)`	Create an empty batch container
`add_tasks(batch_id, tasks)`	Add 1-100 tasks (dicts or `BatchTaskInput`). Batch must be `open` or `processing`
`create_and_run(tasks, wait=False, ...)`	Create + add tasks in one call, optionally waiting for completion
`status(batch_id)`	Current status, task counts, and cost
`list_tasks(batch_id, status=None, include_output=False, limit=25, last_key=None)`	List tasks; set `include_output=True` for full output, sources, images, cost
`wait_for_completion(batch_id, poll_interval=10, max_wait_time=14400, on_progress=None)`	Block until terminal state. Raises `TimeoutError` / `ValueError`
`cancel(batch_id)`	Cancel the batch and its pending tasks
`list(limit=10)`	List batches for your account

Batch-level mode, output_formats, and search are inherited by every task and cannot be overridden per-task. Per-task you can set research_strategy, report_format, urls, and metadata.

Search configuration

The batch-level search config (dict or SearchConfig) applies to all tasks:

from valyu.types.deepresearch import SearchConfig

batch = client.batch.create(
    name="Academic Research",
    mode="standard",
    search=SearchConfig(
        included_sources=["academic", "finance"],
        start_date="2024-01-01",
        end_date="2024-12-31",
    ),
)

See the Batch Processing Guide for all options.

Task input and listing results

from valyu.types.deepresearch import BatchTaskInput

client.batch.add_tasks(batch_id, [
    {"query": "What are the latest trends in AI?"},  # plain dict
    BatchTaskInput(
        id="task-1",
        query="Analyze OpenAI's latest product launches",
        research_strategy="Focus on technical capabilities and market impact",
        report_format="Concise executive summary with bullet points",
        urls=["https://openai.com/blog"],
    ),
])

# Lightweight listing (status only), then full output for completed tasks
results = client.batch.list_tasks(batch_id, status="completed", include_output=True)
for task in results.tasks:
    print(task.task_id or task.deepresearch_id, task.query)
    print(task.output[:200], f"({len(task.sources)} sources, ${task.cost})")

# Paginate
last_key = results.pagination.last_key
while last_key:
    page = client.batch.list_tasks(batch_id, status="completed", include_output=True, last_key=last_key)
    last_key = page.pagination.last_key

Response types

# BatchCreateResponse / BatchStatusResponse expose `.batch` with:
#   batch_id, name, status, mode, output_formats, search_params,
#   counts (total/queued/running/completed/failed/cancelled), cost,
#   created_at, completed_at, webhook_secret (creation only)

# BatchTaskListItem (fields beyond status appear only when include_output=True):
{
    "task_id": Optional[str],
    "deepresearch_id": str,
    "query": str,
    "status": str,
    "output_type": Optional[str],
    "output": Optional[str],
    "sources": Optional[List[Source]],
    "images": Optional[List[str]],
    "pdf_url": Optional[str],
    "deliverables": Optional[Any],
    "cost": Optional[float],
    "error": Optional[str],
}

Webhooks

Pass webhook_url on create() to be notified when the batch reaches a terminal state (completed, completed_with_errors, or cancelled) instead of polling. The webhook_secret is returned only on creation - store it immediately.

Limitations

Batch tasks do not support files, deliverables, mcp_servers, previous_reports, or HITL. Use client.deepresearch.create() for those.

Constraint	Value
Tasks per request	1-100
Batch status to add tasks	`open` or `processing`

Batch Processing Guide

Lifecycle, best practices, and examples

DeepResearch API

Individual task API with all features

TypeScript SDK

TypeScript batch methods

API Reference

REST endpoint documentation

SDKs

DeepResearch Batch

Quick start

Reference

Webhooks

Limitations

See also

Batch Processing Guide

DeepResearch API

TypeScript SDK

API Reference

​Quick start

​Reference

​Webhooks

​Limitations

​See also

Batch Processing Guide

DeepResearch API

TypeScript SDK

API Reference

Quick start

Reference

Webhooks

Limitations

See also