OpenAI Batch

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.

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

Parameter	Type	Required	Default	Description
Model	string	No	gpt-5.4-mini	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.
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

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

Cancel Batch

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

All Operations

Parameter	Type	Required	Default	Description
Options	collection	No	{}
— 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:

{
  "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:

{
  "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 }}.

Example Configuration

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

{
  "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:

{
  "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:

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

Cancel a runaway batch:

{
  "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.