<!-- BusyBot node reference — https://busybot.net/tools/claude-batch/ -->

> Node: Claude Batch (`claude_batch`) · Action · v1
> Category: AI · Credentials: Anthropic (`anthropic`)
> Updated: 2026-08-16

# Claude Batch

> Process multiple Claude messages as a batch job.

## Overview

Claude Batch uses the Anthropic Message Batches API to process multiple Claude message requests asynchronously. Supports three operations: create (collect input items into a batch of message requests), check (poll batch status), and cancel (cancel a processing batch). For the create operation, all input items are submitted as a single batch. Optionally polls for completion with configurable intervals and timeouts. Batch processing offers a 50% cost discount over standard API calls.

**Category:** AI  
**Tool Name:** `claude_batch`  
**Version:** 1

**Appearance:** Icon: `anthropic` | Color: `#d4a574`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **Anthropic** credentials.
See the [Credentials Guide](https://busybot.net/credentials/anthropic/) for setup instructions.

### Operations

| Operation | Value | Description |
|-----------|-------|-------------|
| Create Batch | `create` | Collect upstream items into a single batch. Each input item becomes one batch request |
| Check Status | `check` | Check the status of an existing batch |
| Cancel Batch | `cancel` | Cancel a processing batch |

### Parameters

#### Create Batch (`create`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Model (default) | `string` | No | `Claude Sonnet` | Default Claude model applied to EVERY batch request. Each upstream item can override this by including an `item.model` field. Always uses the latest version (auto-updated) — the field is prefilled with the current Claude Sonnet model ID. |
| System Prompt (default) | `string` | No | — | Default system instructions applied to EVERY batch request. Each upstream item can override this by including an `item.systemPrompt` field. Supports expressions. |

#### Check Status (`check`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Batch ID | `string` | No | — | The batch ID to check or cancel. Falls back to item.json.batchId if empty. Supports expressions. |

#### Cancel Batch (`cancel`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Batch ID | `string` | No | — | The batch ID to check or cancel. Falls back to item.json.batchId if empty. Supports expressions. |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Options | `collection` | No | `{}` | Generation, polling and output settings. |
| — Max Tokens | `number` | No | `4096` | Maximum number of tokens per response in the batch. |
| — Poll Interval (ms) | `number` | No | `30000` | How often to poll for completion status in milliseconds. |
| — Max Poll Duration (ms) | `number` | No | `600000` | Maximum total time to spend polling for completion in milliseconds. |
| — Wait for Completion | `boolean` | No | `false` | If true, poll until the batch completes (or fails/expires) before returning. |
| — Response Field Name | `string` | No | `batch` | Field name in the output JSON where the batch result will be placed. |
| Include Input | `boolean` | No | `false` | Whether to include the original input item fields in the output. |
| Max Concurrency | `number` | No | `5` | Maximum number of items to process concurrently (for check/cancel operations). |

### Per-item fields for Create Batch

Create Batch is the one operation that reads the incoming items rather than a parameter: every item becomes one request in the batch. The node-level Model (default) and System Prompt (default) apply to any item that does not specify its own, so a single batch can mix simple and elaborate requests.

| Item field | Type | What it does |
|---|---|---|
| `message` (also `prompt`, `text`) | string | Single-turn user message for this request |
| `messages` | array | Full multi-turn override — replaces the entire message array for this request. Used instead of `message` when both are present |
| `systemPrompt` | string | Per-item system prompt, overriding the node default for this request only |
| `model` | string | Per-item model, overriding the node default for this request only |
| `attachmentFileId` | string | Anthropic file_id (from Claude File Upload or Claude Code Execution) to attach to the user message |
| `attachmentType` | string | How Claude should interpret the attached file — `document` (the default) or `image`. Ignored when `attachmentFileId` is empty |
| `maxTokens` | number | Per-item token cap, overriding Max Tokens for this request only |
| `temperature` | number | Per-item sampling temperature for this request only |

Build these fields upstream with an Edit Fields, Code or merge node. Anything you leave unset falls back to the node-level default, so there is no need to set every field on every item.

## Output Data

Create Batch submits one batch for the whole node run and then emits one output item per input item, each carrying the same batch metadata. Check Status and Cancel Batch process items individually. Binary data on the input item is forwarded unchanged, and with Include Input on the original item fields are merged in alongside the result.

```json
{
  "batch": { "id": "msgbatch_01...", "processing_status": "in_progress" },
  "batchId": "msgbatch_01...",
  "status": "in_progress",
  "requestCount": 500,
  "resultsUrl": "https://api.anthropic.com/v1/messages/batches/msgbatch_01.../results",
  "requestCounts": { "processing": 480, "succeeded": 20, "errored": 0, "canceled": 0, "expired": 0 }
}
```

- The field named by Response Field Name (`batch` by default) holds the batch object exactly as Anthropic returned it.
- `batchId` and `status` are lifted to the top level for convenience. `batchId` is what a downstream Check Status or Cancel Batch node reads automatically when its own Batch ID is left empty.
- `requestCount` is returned by Create Batch only, and is the number of requests that went into the batch.
- `resultsUrl` and `requestCounts` appear once Anthropic has published them — typically after the batch has ended. `requestCounts` is where you see how many individual requests succeeded or errored; a batch can end successfully with errored requests inside it.
- With Wait for Completion on, the node polls until the batch reports `ended` (or the Max Poll Duration elapses), so the values above are the final ones. With it off, the node returns as soon as the batch is accepted.
- If no input item carried a usable message, Create Batch submits nothing and emits items with a `null` batch, `batchId: null` and `status: "empty"`.

Reference the result downstream by expression, e.g. `{{ $json.batchId }}`.

## Usage Examples

- Submit 500 prompts as a single Claude batch for 50% cost savings
- Check the status of a running Claude batch job
- Cancel a processing Claude batch
- Create a batch of Claude messages with a system prompt
- Submit batch with polling to wait for completion

## Example Configuration

Create a batch and continue immediately:

```json
{
  "type": "claude_batch",
  "parameters": {
    "operation": "create",
    "systemPrompt": "You are a concise summarization assistant. Return only the summary.",
    "options": {
      "maxTokens": 1024,
      "waitForCompletion": false,
      "responseFieldName": "batch"
    }
  }
}
```

Create a batch and block until every request has been processed:

```json
{
  "type": "claude_batch",
  "parameters": {
    "operation": "create",
    "systemPrompt": "Classify the sentiment of the provided text as positive, negative, or neutral.",
    "includeInput": true,
    "options": {
      "maxTokens": 256,
      "waitForCompletion": true,
      "pollIntervalMs": 20000,
      "maxPollDurationMs": 900000,
      "responseFieldName": "sentimentResult"
    }
  }
}
```

Check a batch created earlier, taking the ID from the incoming item:

```json
{
  "type": "claude_batch",
  "parameters": {
    "operation": "check",
    "batchId": "",
    "options": {
      "waitForCompletion": true,
      "pollIntervalMs": 30000,
      "maxPollDurationMs": 600000,
      "responseFieldName": "batch"
    }
  }
}
```

Cancel a batch by ID:

```json
{
  "type": "claude_batch",
  "parameters": {
    "operation": "cancel",
    "batchId": "{{ $json.batchId }}",
    "options": {
      "responseFieldName": "cancelResult"
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Claude Batch submits multiple Claude message requests to the Anthropic Message Batches API asynchronously, supporting create, check, and cancel operations at a 50% cost discount over standard API calls. Use it when processing large volumes of independent prompts where real-time responses are unnecessary and minimizing inference cost is a priority. It outputs per-request response data to the main channel upon batch completion, or routes submission and processing failures to the error channel.