Grok Structured Output

Get structured JSON responses from xAI Grok with schema enforcement.

Overview

Grok Structured Output sends a user message to the xAI Grok API with a JSON schema constraint, forcing the model to return valid JSON matching the provided schema. Supports model selection, system prompts, temperature, max tokens, and strict mode. Returns the parsed structured JSON, model name, token usage, and finish reason.

Category: AI
Tool Name: grok_structured_output
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.

Parameters

Parameter	Type	Required	Default	Description
Model	options	No	Platform default	The Grok model to use for structured output generation.
				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.
JSON Schema	json	Yes	{}	The JSON Schema that the model response must conform to. Can be a JSON object or a string that will be parsed.
Options	collection	No	{}	Optional generation and output 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.
— Strict	boolean	No	true	Enable strict schema enforcement. When true, the model is constrained to only produce output matching the exact schema.
— Response Field Name	string	No	structured	The output field name where the parsed structured JSON will be stored.
Include Input	boolean	No	false	Whether to include the original input item fields in the output alongside the structured response.
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

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

• structured — the parsed JSON object matching your schema, under whatever name Response Field Name is set to.
• model — the model that produced the response.
• usage — the token counts reported by xAI for the request.
• finishReason — why generation stopped, as reported by xAI.

If the model’s reply cannot be parsed as JSON, the response field holds _raw (the unparsed text) and _parseError (the parser message) instead of your schema’s fields — a useful thing to branch on downstream.

Reference the result downstream by expression, e.g. {{ $json.structured.sentiment }}.

Usage Examples

• Extract structured data from unstructured text using a JSON schema
• Parse entities from a document into a defined JSON format with Grok
• Generate structured product descriptions matching a schema
• Convert free-text responses into typed JSON objects with strict mode
• Use Grok to classify items and return results in a fixed schema

Example Configuration

Classify a review into a fixed shape:

{
  "type": "grok_structured_output",
  "parameters": {
    "systemPrompt": "You are a precise sentiment analysis engine.",
    "userMessage": "Analyse the sentiment of this review: {{ $json.reviewText }}",
    "jsonSchema": {
      "type": "object",
      "properties": {
        "sentiment": { "type": "string", "enum": ["positive", "neutral", "negative"] },
        "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
        "reasoning": { "type": "string" }
      },
      "required": ["sentiment", "confidence", "reasoning"],
      "additionalProperties": false
    },
    "includeInput": true,
    "options": {
      "temperature": 0.1,
      "maxTokens": 512,
      "strict": true
    }
  }
}

Extract named entities into a custom output field:

{
  "type": "grok_structured_output",
  "parameters": {
    "userMessage": "Extract all named entities from: {{ $json.text }}",
    "jsonSchema": {
      "type": "object",
      "properties": {
        "people": { "type": "array", "items": { "type": "string" } },
        "organizations": { "type": "array", "items": { "type": "string" } },
        "locations": { "type": "array", "items": { "type": "string" } }
      },
      "required": ["people", "organizations", "locations"],
      "additionalProperties": false
    },
    "options": {
      "temperature": 0,
      "maxTokens": 2048,
      "responseFieldName": "entities"
    }
  }
}

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 Structured Output sends a prompt to the xAI Grok API with a JSON schema constraint, forcing the model to return valid JSON that exactly matches the provided schema. Use it when downstream workflow nodes require machine-readable, typed data such as extracted entities, classifications, or structured records rather than free-form text. It produces the parsed JSON object, the Grok model variant used, prompt and completion token counts, and the finish reason.