Skip to main content
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

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

# 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.
ConstraintValue
Tasks per request1-100
Batch status to add tasksopen or processing

​
See also

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