DeepResearch Batch API | TypeScript 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 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

Methods

Method	Description
`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.

Search configuration

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.

Task input and listing results

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;
}

Response types

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.

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

Python SDK

Python batch methods

API Reference

REST endpoint documentation

SDKs

DeepResearch Batch

Quick start

Reference

Webhooks

Limitations

See also

Batch Processing Guide

DeepResearch API

Python SDK

API Reference

​Quick start

​Reference

​Webhooks

​Limitations

​See also

Batch Processing Guide

DeepResearch API

Python SDK

API Reference

Quick start

Reference

Webhooks

Limitations

See also