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 TypeScript 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 TypeScript SDK.

Open in Cursor

​
Quick start

Create a batch, add 1-100 tasks, then wait for completion: 
import { Valyu } from "valyu-js";

const client = new Valyu();

const batch = await client.batch.create({ name: "Research Batch", mode: "standard" });

await client.batch.addTasks(batch.batch_id, {
  tasks: [
    { query: "Research AI trends" },
    { query: "Analyze market data" },
  ],
});

const finalBatch = await client.batch.waitForCompletion(batch.batch_id, {
  onProgress: (b) => console.log(`${b.counts.completed}/${b.counts.total} completed`),
});

const results = await client.batch.listTasks(batch.batch_id, { status: "completed", includeOutput: true });
for (const t of results.tasks) {
  console.log(t.query, "->", t.output?.substring(0, 200), "cost:", t.cost);
}

​
Reference

MethodDescription
batch.create({ name, mode, outputFormats, search, webhookUrl, metadata })Create an empty batch container
batch.addTasks(batchId, { tasks })Add 1-100 tasks. Batch must be open or processing
batch.status(batchId)Current status, task counts, and cost
batch.listTasks(batchId, { status?, includeOutput?, limit?, lastKey? })List tasks; set includeOutput: true for full output, sources, images, cost
batch.waitForCompletion(batchId, { pollInterval?, maxWaitTime?, onProgress? })Block until terminal state
batch.cancel(batchId)Cancel the batch and its pending tasks
batch.list()List batches for your API key
Batch-level mode, outputFormats, and search are inherited by every task and cannot be overridden per-task. Per-task you can set researchStrategy, reportFormat, urls, and metadata.Individual tasks are DeepResearch tasks - use deepresearch.status(task.deepresearch_id), deepresearch.update(...), or deepresearch.cancel(...) on them directly.
The batch-level search config applies to all tasks:
const batch = await client.batch.create({
  name: "Academic Research",
  mode: "standard",
  search: {
    includedSources: ["academic", "finance"],
    startDate: "2024-01-01",
    endDate: "2024-12-31",
  },
});
See the Batch Processing Guide for all options.
await client.batch.addTasks(batchId, {
  tasks: [
    { query: "What are the latest developments in quantum computing?" },
    {
      query: "Compare renewable energy trends across Europe",
      researchStrategy: "Focus on policy and adoption rates",
      urls: ["https://example.com/report.pdf"],
    },
  ],
});

// Full output for completed tasks
const results = await client.batch.listTasks(batchId, { status: "completed", includeOutput: true });
for (const task of results.tasks) {
  console.log(task.task_id || task.deepresearch_id, task.query);
  console.log(task.output?.substring(0, 200), `(${task.sources?.length} sources, $${task.cost})`);
}

// Paginate
let lastKey = results.pagination.last_key;
while (lastKey) {
  const page = await client.batch.listTasks(batchId, { status: "completed", includeOutput: true, lastKey });
  lastKey = page.pagination.last_key;
}

interface DeepResearchBatch {
  batch_id: string;
  name?: string;
  status: "open" | "processing" | "completed" | "completed_with_errors" | "cancelled";
  mode: "fast" | "standard" | "heavy" | "max";
  output_formats?: ("markdown" | "pdf" | "toon" | Record<string, any>)[];
  search_params?: { search_type?: string; included_sources?: string[] };
  counts: { total; queued; running; completed; failed; cancelled };
  cost: number;
  created_at: string;
  completed_at?: string;
  webhook_secret?: string;  // creation only
}

// BatchTaskListItem (fields beyond status appear only when includeOutput is true):
interface BatchTaskListItem {
  task_id?: string;
  deepresearch_id: string;
  query: string;
  status: DeepResearchStatus;
  output_type?: string;
  output?: string;
  sources?: Source[];
  images?: string[];
  pdf_url?: string;
  cost?: number;
  error?: string;
}

​
Webhooks

Pass webhookUrl 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, mcpServers, previousReports, 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

Python SDK

Python batch methods

API Reference

REST endpoint documentation