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

> Node: Grok Batch (`grok_batch`) · Action · v1
> Category: AI · Credentials: xAI (`xai`)
> Updated: 2026-08-16

# 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](https://busybot.net/credentials/xai/) 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:

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

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

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

Cancel a batch that is no longer needed:

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