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

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

# Grok Chat

> Chat with xAI Grok models using the OpenAI-compatible API.

## Overview

Grok Chat sends a user message (with an optional system prompt) to the xAI Grok API and returns the model's response. Supports model selection, temperature, max tokens, top-p, frequency penalty, and presence penalty. Returns the assistant's message text, model name, token usage, and finish reason.

**Category:** AI  
**Tool Name:** `grok_chat`  
**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.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Model | `options` | No | Platform default | The Grok model to use for chat completion. |
| | | | | 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 | — | Optional system prompt to set the behavior and context for the model. Supports expressions like {{ $json.persona }}. |
| User Message | `string` | Yes | — | The user message to send to Grok. If empty, falls back to the input item's "message" or "prompt" field. Supports expressions. |
| Options | `collection` | No | `{}` | Optional generation settings — add only the fields you want to override. |
| — Temperature | `number` | No | `1` | Controls randomness. Lower values make output more focused; higher values more creative. Range: 0-2. |
| — Max Tokens | `number` | No | `4096` | Maximum number of tokens to generate in the response. |
| — Top P | `number` | No | `1` | Nucleus sampling: only tokens with top-p cumulative probability are considered. Range: 0-1. |
| — Frequency Penalty | `number` | No | `0` | Penalizes tokens based on their frequency in the text so far. Range: -2 to 2. |
| — Presence Penalty | `number` | No | `0` | Penalizes tokens based on whether they appear in the text so far. Range: -2 to 2. |
| — Response Field Name | `string` | No | `response` | The output field name where the AI response text will be stored. |
| Include Input | `boolean` | No | `false` | Whether to include the original input item fields in the output alongside the AI response. |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

One output item per input item. The reply text is written to the field named by Response Field Name (`response` by default). The rest of the input JSON is carried over only when Include Input is on; binary data from the input item is always forwarded.

- `response` — the assistant's reply text, under whatever name Response Field Name is set to.
- `model` — the model that produced the reply.
- `usage` — the token counts reported by xAI for the request.
- `finishReason` — why generation stopped, as reported by xAI.

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

## Usage Examples

- Ask Grok a question and get a text response
- Generate content using Grok with a system prompt
- Process a batch of prompts through Grok
- Use a faster Grok model for quick completions with low latency
- Chat with Grok using custom temperature and max tokens

## Example Configuration

Ask a single question with the defaults:

```json
{
  "type": "grok_chat",
  "parameters": {
    "userMessage": "What is the capital of France?"
  }
}
```

Answer with a system prompt and tighter generation settings:

```json
{
  "type": "grok_chat",
  "parameters": {
    "systemPrompt": "You are a careful analyst. Answer in one paragraph.",
    "userMessage": "Summarise the risks in this report: {{ $json.body }}",
    "options": {
      "temperature": 0.3,
      "maxTokens": 2048,
      "responseFieldName": "analysis"
    }
  }
}
```

Classify a batch of items, reading each prompt from the item itself:

```json
{
  "type": "grok_chat",
  "parameters": {
    "systemPrompt": "Classify the sentiment as exactly one of: positive, negative, neutral.",
    "userMessage": "",
    "includeInput": true,
    "maxConcurrency": 20,
    "options": {
      "temperature": 0,
      "maxTokens": 16,
      "responseFieldName": "sentiment"
    }
  }
}
```

### 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 Chat sends a user message and optional system prompt to xAI Grok models via an OpenAI-compatible chat completions API, with controls for temperature, max tokens, top-p, and frequency and presence penalties. Use it when your workflow requires generation or reasoning tasks routed specifically to xAI Grok models. It outputs the assistant response text, model name, token usage counts, and finish reason on the main channel, or routes failures to the error output.