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

> Node: OpenAI Batch (`openai_batch`) · Action · v1
> Category: AI · Credentials: OpenAI (`openai`)
> Updated: 2026-08-16

# OpenAI Batch

> Process multiple requests as a batch job via OpenAI Batch API.

## Overview

OpenAI Batch uses the OpenAI Batch API to process multiple chat completion or embedding requests asynchronously. Supports three operations: create (build JSONL from input items, upload as file, create batch), check (poll batch status), and cancel (cancel a running batch). For the create operation, all input items are collected into a single batch request. Optionally polls for completion with configurable intervals and timeouts.

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

**Appearance:** Icon: `openai` | Color: `#10a37f`

## Node Type

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

## Input / Output

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

## Credentials

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

### Operations

| Operation | Value | Description |
|-----------|-------|-------------|
| Create Batch | `create` | Create a new batch job from input items. |
| Check Status | `check` | Check the status of an existing batch. |
| Cancel Batch | `cancel` | Cancel a running batch. |

### Parameters

#### Create Batch (`create`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Model | `string` | No | (current default) | The OpenAI model to use for batch requests. Falls back to the centralized default if empty. Each item can override via item.model. |
| System Prompt | `string` | No | — | System instructions applied to all batch requests. Only applies to create operation. Supports expressions. |
| Endpoint | `options` | No | `/v1/chat/completions` | The API endpoint for batch requests. |
| | | | | Options: `/v1/chat/completions` (batch chat completion requests), `/v1/embeddings` (batch embedding requests) |

#### 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 | `{}` | Optional batch and polling settings — add only the fields you need. |
| — Completion Window | `string` | No | `24h` | Time window for batch completion. Currently only "24h" is supported by OpenAI. |
| — 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). |

## Output Data

The batch object lands on the field named by **Response Field Name** (`batch` by default), with the fields you normally branch on lifted to the top level. The rest of the input item JSON is dropped unless **Include Input** is on; binary data on the input item is forwarded unchanged.

`Create Batch` collapses every input item into **one** batch job, then emits one output item per input item, all carrying the same batch result:

```json
{
  "batch": { "id": "batch_abc123", "status": "validating" },
  "batchId": "batch_abc123",
  "status": "validating",
  "inputFileId": "file-abc123",
  "requestCount": 1000
}
```

`Check Status` and `Cancel Batch` process items independently, one output item per input item:

```json
{
  "batch": { "id": "batch_abc123", "status": "completed" },
  "batchId": "batch_abc123",
  "status": "completed",
  "outputFileId": "file-def456",
  "requestCounts": { "total": 1000, "completed": 1000, "failed": 0 }
}
```

| Operation | Fields on the output item |
|-----------|---------------------------|
| `create` | `batchId`, `status`, `inputFileId`, `requestCount` — plus `outputFileId` once results exist. When no input item yielded a usable request, `batchId` is `null` and `status` is `empty` |
| `check` | `batchId`, `status` — plus `outputFileId` and `requestCounts` when the API reports them |
| `cancel` | `batchId`, `status` — plus `outputFileId` and `requestCounts` when the API reports them |

- `status` follows the batch through its life: validating, in progress, completed, failed, expired or cancelled. With **Wait for Completion** on, the node returns only once it reaches a terminal state.
- `outputFileId` points at the results file in your OpenAI account. Retrieve it there once the batch completes.

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

## Usage Examples

- Submit 1000 prompts as a single OpenAI batch for cost savings
- Check the status of a running OpenAI batch job
- Cancel a pending OpenAI batch
- Create a batch of embeddings requests
- Submit batch with polling to wait for completion

## Example Configuration

Submit every incoming item as one chat-completion batch and return immediately:

```json
{
  "type": "openai_batch",
  "parameters": {
    "operation": "create",
    "systemPrompt": "Summarize the text in one sentence.",
    "endpoint": "/v1/chat/completions"
  }
}
```

Create an embedding batch and wait for it to finish:

```json
{
  "type": "openai_batch",
  "parameters": {
    "operation": "create",
    "endpoint": "/v1/embeddings",
    "options": {
      "waitForCompletion": true,
      "pollIntervalMs": 60000,
      "maxPollDurationMs": 3600000
    }
  }
}
```

Check the status of a batch created earlier in the workflow:

```json
{
  "type": "openai_batch",
  "parameters": {
    "operation": "check",
    "batchId": "{{ $json.batchId }}"
  }
}
```

Cancel a runaway batch:

```json
{
  "type": "openai_batch",
  "parameters": {
    "operation": "cancel",
    "batchId": "{{ $json.batchId }}"
  }
}
```

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

OpenAI Batch processes multiple chat completion or embedding requests asynchronously by bundling input items into a JSONL file and submitting them as a single batch job. Use it when handling large volumes of requests that do not require immediate responses, such as bulk content generation or dataset embedding runs. It outputs batch status and completed response data for each input item on the main channel, or routes failures to the error channel.