> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valyu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Note>
  For individual tasks with unique configurations or advanced features (files, deliverables, MCP servers), use the standard [DeepResearch API](/guides/deepresearch) instead.
</Note>

## Quick Example

<CodeGroup>
  ```python Python theme={null}
  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}")
  ```

  ```typescript TypeScript theme={null}
  import { Valyu } from "valyu-js";

  const valyu = new Valyu();

  // 1. Create a batch
  const batch = await valyu.batch.create({
    name: "Market Research Q4",
    mode: "standard",
    outputFormats: ["markdown"]
  });

  if (batch.success) {
    // 2. Add tasks
    await valyu.batch.addTasks(batch.batch_id, {
      tasks: [
        { query: "Analyze AI trends in healthcare" },
        { query: "Review renewable energy market" },
        { query: "Research fintech innovations" }
      ]
    });
    
    // 3. Wait for completion
    const result = await valyu.batch.waitForCompletion(batch.batch_id, {
      onProgress: (batch) => {
        console.log(`Progress: ${batch.counts.completed}/${batch.counts.total}`);
      }
    });
    
    console.log(`Completed! Total cost: $${result.cost}`);
  }
  ```

  ```bash cURL theme={null}
  # 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",
      "mode": "standard",
      "output_formats": ["markdown"]
    }'

  # Add tasks (use batch_id from 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 AI trends in healthcare"},
        {"query": "Review renewable energy market"},
        {"query": "Research fintech innovations"}
      ]
    }'
  ```
</CodeGroup>

## 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

<CodeGroup>
  ```python Python theme={null}
  # 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")
  ```

  ```typescript TypeScript theme={null}
  // Get all completed results with full output
  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`);
  }
  ```

  ```bash cURL theme={null}
  curl -X GET "https://api.valyu.ai/v1/deepresearch/batches/${BATCH_ID}/tasks?status=completed&include_output=true" \
    -H "X-API-Key: ${VALYU_API_KEY}"
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Complete Guide" icon="book" href="/guides/deepresearch-batching">
    Full batch documentation with search configuration, webhooks, and best practices
  </Card>

  <Card title="Python SDK" icon="python" href="/sdk/python-sdk/deepresearch-batch">
    Complete Python SDK reference for batch operations
  </Card>

  <Card title="TypeScript SDK" icon="js" href="/sdk/typescript-sdk/deepresearch-batch">
    Complete TypeScript SDK reference for batch operations
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/endpoint/deepresearch-batch-create">
    REST API endpoint documentation
  </Card>
</CardGroup>