Grok Chat

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.

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.

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.
— 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.
Web Search	boolean	No	false	Enable xAI’s server-side search tools. When on, Grok may search before answering and returns cited sources in the sources output field.
Search Sources	multiOptions	No	["web"]	Which xAI search surfaces Grok may use. Select both to let Grok choose per query. (shown when Web Search is on)
				Options: web (public web via the xAI web_search tool), x (X/Twitter posts via the x_search tool)
Search From Date	string	No	—	Only consider results published on or after this date. Accepts YYYY-MM-DD or a full ISO timestamp. Leave empty for no lower bound. Supports expressions. (shown when Web Search is on)
Search To Date	string	No	—	Only consider results published on or before this date. Accepts YYYY-MM-DD or a full ISO timestamp. Leave empty for no upper bound. Supports expressions. (shown when Web Search is on)
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 }}.

• sources is always present: an array of cited results when Web Search is on, and an empty array when it is off. Each entry carries url and title.
• usage now carries both naming schemes. prompt_tokens / completion_tokens / total_tokens are kept as aliases so existing expressions keep working, alongside the Responses API’s own input_tokens / output_tokens / num_server_side_tools_used.
• finishReason keeps the familiar stop / length / content_filter / tool_calls vocabulary. The raw Responses values are exposed additively as status and incompleteReason.
• Frequency Penalty and Presence Penalty were removed. The Responses API has no equivalent and silently ignores them, so they were retired rather than left as controls that do nothing. Saved workflows carrying those keys keep running — the values are simply ignored.

Example Configuration

Ask a single question with the defaults:

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

Answer with a system prompt and tighter generation settings:

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

{
  "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 user messages to xAI Grok models for text generation. It is the right tool when your task requires content generation or reasoning specifically from xAI Grok models, optionally with web or X search. It produces the assistant’s message text, any cited sources, the model name, token usage, and the finish reason.