Grok Batch

Process multiple Grok requests as a batch job.

Overview

Grok Batch uses the xAI Batch API to process many chat completion requests asynchronously. Three operations are supported: create (collect the incoming items into one batch job and submit it), check (look up a batch’s status), and cancel (stop a running batch). On create, every input item is folded into a single batch request. The node can optionally poll for completion with a configurable interval and timeout.

Category: AI
Tool Name: grok_batch
Version: 1

Appearance: Icon: brain | Color: #000000

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires xAI 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 (create)

Parameter	Type	Required	Default	Description
Model	options	No	Platform default	The Grok model to use for batch requests.
				Options: the Grok chat models currently available — the dropdown tracks the model catalog, so it changes as xAI’s line-up changes.
System Prompt	string	No	—	System instructions applied to all batch requests. Only applies to create operation. Supports expressions.

There is no prompt parameter on this operation. The user message for each batch request is read from the input item’s message, prompt or text field, in that order; items with none of those fields are skipped.

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, polling and output settings — add only the fields you want to override.
— Completion Window	string	No	24h	Time window for batch completion.
— 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. Applies to the create operation.
— 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

One output item per input item in every operation — create submits one batch for the whole run but still echoes the result back onto each item. The rest of the input JSON is carried over only when Include Input is on; binary data from the input item is forwarded.

The batch record is written to the field named by Response Field Name (batch by default), alongside these flat fields:

Operation	Fields on the output item
create	batch (the batch record, polled to its terminal state when Wait for Completion is on), batchId, status, inputFileId, requestCount (how many requests went into the batch), and outputFileId once xAI has produced results
check / cancel	batch (the batch record), batchId, status, plus outputFileId and requestCounts when xAI returns them

If no input item carries a usable prompt, create emits one item per input with batch: null, batchId: null and status: "empty" rather than submitting anything.

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

Usage Examples

• Submit 1000 prompts as a single Grok batch job
• Check the status of a running Grok batch
• Cancel a pending Grok batch
• Create a batch of Grok chat completions
• Submit batch with polling to wait for completion

Example Configuration

Submit the incoming items as one batch and return immediately:

{
  "type": "grok_batch",
  "parameters": {
    "operation": "create",
    "systemPrompt": "Extract the key entities from the provided text and return them as a JSON array.",
    "includeInput": true,
    "options": {
      "completionWindow": "24h",
      "waitForCompletion": false
    }
  }
}

Submit and block until the batch finishes:

{
  "type": "grok_batch",
  "parameters": {
    "operation": "create",
    "systemPrompt": "Translate the following text to Spanish.",
    "options": {
      "completionWindow": "2h",
      "waitForCompletion": true,
      "pollIntervalMs": 20000,
      "maxPollDurationMs": 360000,
      "responseFieldName": "translationBatch"
    }
  }
}

Check a batch created by an earlier node:

{
  "type": "grok_batch",
  "parameters": {
    "operation": "check",
    "batchId": "{{ $json.batchId }}",
    "maxConcurrency": 5
  }
}

Cancel a batch that is no longer needed:

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

Grok Batch processes multiple xAI chat completion requests together by building a JSONL file, uploading it, and submitting it as a single asynchronous batch job. Use it when handling large volumes of Grok prompts where real-time responses are not required, reducing overhead compared to individual API calls. It outputs batch status information and completed chat completion results on the main channel, with failures routed to the error channel.