Skip to main content
The Batch API runs 1-100 DeepResearch tasks in parallel with shared configuration, unified monitoring, and aggregated cost tracking. Use it for bulk research where many queries share the same mode, output formats, and search settings. For individual tasks with unique config or advanced features (files, deliverables, MCP servers), use the standard DeepResearch API. New to DeepResearch? Read that guide first.

​
Workflow: create, add tasks, wait

Create a batch with shared settings, add queries, then poll until done. 
from valyu import Valyu

valyu = Valyu()

# 1. Create a batch with default settings for all tasks
batch = valyu.batch.create(
    name="Market Research Q4 2024",
    mode="standard",
    output_formats=["markdown"],
    search={"included_sources": ["web", "academic"], "start_date": "2024-01-01"},
)

# 2. Add tasks (1-100 per request)
valyu.batch.add_tasks(batch.batch_id, [
    {"query": "Analyze technology sector performance in Q4 2024"},
    {"query": "Research healthcare sector trends and key players"},
    {"query": "Review renewable energy market developments"},
])

# 3. Wait for completion
final = valyu.batch.wait_for_completion(
    batch.batch_id,
    poll_interval=10,
    on_progress=lambda s: print(
        f"{s.batch.counts.completed}/{s.batch.counts.total} done"
    ),
)
print(f"Status: {final.batch.status}, cost: ${final.batch.cost}")

import { Valyu } from "valyu-js";

const valyu = new Valyu();

// 1. Create a batch with default settings for all tasks
const batch = await valyu.batch.create({
  name: "Market Research Q4 2024",
  mode: "standard",
  outputFormats: ["markdown"],
  search: { includedSources: ["web", "academic"], startDate: "2024-01-01" },
});

// 2. Add tasks (1-100 per request)
await valyu.batch.addTasks(batch.batch_id, {
  tasks: [
    { query: "Analyze technology sector performance in Q4 2024" },
    { query: "Research healthcare sector trends and key players" },
    { query: "Review renewable energy market developments" },
  ],
});

// 3. Wait for completion
const final = await valyu.batch.waitForCompletion(batch.batch_id, {
  pollInterval: 10000,
  onProgress: (b) => console.log(`${b.counts.completed}/${b.counts.total} done`),
});
console.log(`Status: ${final.status}, cost: $${final.cost}`);

# Create a batch
curl -X POST "https://api.valyu.ai/v1/deepresearch/batches" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "Market Research Q4 2024",
    "mode": "standard",
    "output_formats": ["markdown"],
    "search": { "included_sources": ["web", "academic"], "start_date": "2024-01-01" }
  }'

# Add tasks (use batch_id from the response)
curl -X POST "https://api.valyu.ai/v1/deepresearch/batches/BATCH_ID/tasks" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "tasks": [
      {"query": "Analyze technology sector performance in Q4 2024"},
      {"query": "Research healthcare sector trends and key players"},
      {"query": "Review renewable energy market developments"}
    ]
  }'

​
Shared vs per-task configuration

Tasks inherit mode, output_formats, and search from the batch and cannot override them. Each task can set its own research_strategy, report_format, urls, and metadata. Mode pricing and search parameters are identical to standard DeepResearch - see the search configuration section for the full source list, date filters, and category options. Set them in the batch search object and they apply to every task.

​
Retrieve results

Use list_tasks with include_output=True to get full outputs. It’s paginated; follow pagination.last_key for more pages. 
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, cost: ${task.cost}")

# Next page
last_key = results.pagination.last_key
while last_key:
    page = valyu.batch.list_tasks(
        batch_id, status="completed", include_output=True, last_key=last_key
    )
    for task in page.tasks:
        print(task.query)
    last_key = page.pagination.last_key

const results = await valyu.batch.listTasks(batchId, {
  status: "completed",
  includeOutput: true,
});

for (const task of results.tasks) {
  console.log(`Query: ${task.query}`);
  console.log(`Output: ${task.output?.substring(0, 200)}...`);
  console.log(`Sources: ${task.sources?.length} cited, cost: $${task.cost}`);
}

// Next page
let lastKey = results.pagination.last_key;
while (lastKey) {
  const page = await valyu.batch.listTasks(batchId, {
    status: "completed",
    includeOutput: true,
    lastKey,
  });
  for (const task of page.tasks) console.log(task.query);
  lastKey = page.pagination.last_key;
}

curl -X GET "https://api.valyu.ai/v1/deepresearch/batches/${BATCH_ID}/tasks?status=completed&include_output=true&limit=25" \
  -H "X-API-Key: ${VALYU_API_KEY}"
include_output defaults to false for a lightweight status-only listing. Set it to true only when you need full output, sources, and cost per task.

​
Batch and task statuses

Batch statusMeaning
openCreated, ready to accept tasks
processingAt least one task is queued, running, or completed
completedAll tasks finished successfully
completed_with_errorsAll tasks finished, some failed
cancelledCancelled before completion
Individual tasks use the standard queued / running / completed / failed / cancelled states.

​
Webhooks

Set a webhook_url to get notified when the batch reaches a terminal state (completed, completed_with_errors, or cancelled) instead of polling. 
batch = valyu.batch.create(
    name="Research Batch",
    mode="standard",
    webhook_url="https://your-domain.com/webhook"
)
# Save the secret immediately - it's only returned once
webhook_secret = batch.webhook_secret

​
Limitations

The batch API does not support deliverables, files, mcp_servers, previous_reports, or alert_email, and code_execution is always on. Use individual task creation (POST /v1/deepresearch/tasks) if you need any of these. Other constraints: 1-100 tasks per request; the batch must be open or processing to add tasks; the deprecated lite mode maps to standard.

​
Next steps

DeepResearch guide

Individual task features: files, deliverables, MCP servers

Python SDK

Python batch methods

TypeScript SDK

TypeScript batch methods

API reference

Batch endpoint documentation