Batch Processing Quickstart

Run multiple research tasks in parallel with shared configuration

The Batch API lets you run multiple DeepResearch tasks in parallel with shared configuration, unified monitoring, and aggregated cost tracking.

When to Use Batching

• Bulk operations - Process 10-100 research queries at once
• Shared settings - Apply the same mode, output formats, and search filters to all tasks
• Unified tracking - Monitor progress and costs across all tasks in one place

For individual tasks with unique configurations or advanced features (files, deliverables, MCP servers), use the standard DeepResearch API instead.

Quick Example

Python

from valyu import Valyu

valyu = Valyu()

# 1. Create a batch
batch = valyu.batch.create(
    name="Market Research Q4",
    mode="standard",
    output_formats=["markdown"]
)

if batch.success:
    # 2. Add tasks
    valyu.batch.add_tasks(batch.batch_id, [
        {"query": "Analyze AI trends in healthcare"},
        {"query": "Review renewable energy market"},
        {"query": "Research fintech innovations"}
    ])
    
    # 3. Wait for completion
    result = valyu.batch.wait_for_completion(
        batch.batch_id,
        on_progress=lambda s: print(f"Progress: {s.batch.counts.completed}/{s.batch.counts.total}")
    )
    
    print(f"Completed! Total cost: ${result.batch.cost}")

Batch Lifecycle

Status	Description
open	Batch created, ready to accept tasks
processing	Tasks are queued, running, or completed
completed	All tasks finished successfully
completed_with_errors	All tasks finished, some failed
cancelled	Batch was cancelled

Retrieve Results

Python

# Get all completed results with full output
results = valyu.batch.list_tasks(batch_id, status="completed", include_output=True)

for task in results.tasks:
    print(f"Query: {task.query}")
    print(f"Output: {task.output[:200]}...")
    print(f"Sources: {len(task.sources)} cited")

Next Steps

Complete Guide

Full batch documentation with search configuration, webhooks, and best practices

Python SDK

Complete Python SDK reference for batch operations

TypeScript SDK

Complete TypeScript SDK reference for batch operations

API Reference

REST API endpoint documentation