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

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

# 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](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 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:

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

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