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

> Node: Structured Output (`structured_output`) · Action · v1
> Category: AI · Credentials: OpenAI API Credentials (`openai`)
> Updated: 2026-08-16

# Structured Output

> Extract structured data with AI

## Overview

Extract structured data from content using OpenAI's Structured Output API. Define a JSON Schema to specify the exact shape of the response, enabling reliable extraction of arrays, objects, and typed fields from unstructured text.

**Category:** AI  
**Tool Name:** `structured_output`  
**Version:** 1

**Appearance:** Icon: `structuredOutput` | Color: `#8b5cf6`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **OpenAI API Credentials** credentials.
See the [Credentials Guide](https://busybot.net/credentials/openai/) for setup instructions.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| System Prompt | `string` | No | `You are a data extraction assistant. Extract the requested information from the provided content accurately and completely.` | System message that instructs the model on extraction behavior. Supports expressions like {{ $json.field }}. |
| User Prompt | `string` | Yes | `Extract data from the following content:\n\n{{ $json.content }}` | The user message containing the content to process. Use expressions like {{ $json.field }} to inject item data. |
| Schema Name | `string` | Yes | `extracted_data` | A name identifier for the JSON Schema (snake_case recommended). Used by OpenAI to reference the schema. |
| Schema Definition | `string` | Yes | `{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"},"description":"List of extracted items"}},"required":["items"],"additionalProperties":false}` | JSON Schema definition specifying the structure of the expected output. Must be valid JSON Schema. Use additionalProperties: false for strict mode. |
| Model | `options` | No | `gpt-4o-mini` | The OpenAI model to use. Must support structured outputs (gpt-4o, gpt-4o-mini, o1, o1-mini, o3-mini). |
| | | | | Options: `gpt-4o`, `gpt-4o-mini`, `o1`, `o1-mini`, `o3-mini` |
| Strict Mode | `boolean` | No | `true` | When enabled, the model's output will strictly adhere to the schema. Requires additionalProperties: false in schema. |
| Max Concurrency | `number` | No | `25` | Maximum number of concurrent API calls to OpenAI. |
| Output Field Name | `string` | No | `structuredOutput` | The field name to store the structured output result in the output item. |
| Include Input in Output | `boolean` | No | `true` | If true, includes the original input data in the output item alongside the structured result. |

## Output Data

One output item per input item. The extracted object is written to the field named by Output Field Name (`structuredOutput` by default), alongside a `structuredOutputMetadata` block. With Include Input in Output on — the default — the original item fields are kept underneath; turn it off to return only the extraction and its metadata. Binary data is forwarded either way.

```json
{
  "structuredOutput": { "items": ["invoice 4471", "invoice 4472"] },
  "structuredOutputMetadata": {
    "schemaName": "extracted_data",
    "model": "gpt-4o-mini",
    "strictMode": true,
    "usage": { "promptTokens": 743, "completionTokens": 58, "totalTokens": 801 },
    "finishReason": "stop",
    "processedAt": 1765432100000
  }
}
```

- The value on the output field always matches the shape declared in Schema Definition, so downstream expressions can address its fields directly.
- `finishReason` is the model's own stop reason. A value such as `length` means the response was cut short and the extraction may be incomplete.
- `usage` reports the token counts for that single call, which is what the run is billed on.
- If the model declines to answer, the item becomes an error rather than a partial result.

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

## Usage Examples

- extract names and dates from the document
- parse the email for key information
- pull out product details from the description
- identify entities in the text
- structure the resume data into fields

## Example Configuration

Extract a list of items from each item's `content` field, using the default one-property schema:

```json
{
  "type": "structured_output",
  "parameters": {
    "systemPrompt": "You are a data extraction assistant. Extract the requested information from the provided content accurately and completely.",
    "userPrompt": "Extract data from the following content:\n\n{{ $json.content }}",
    "schemaName": "extracted_data",
    "schemaDefinition": "{\n  \"type\": \"object\",\n  \"properties\": {\n    \"items\": {\n      \"type\": \"array\",\n      \"items\": {\n        \"type\": \"string\"\n      },\n      \"description\": \"List of extracted items\"\n    }\n  },\n  \"required\": [\"items\"],\n  \"additionalProperties\": false\n}",
    "model": "gpt-4o-mini",
    "strictMode": true,
    "maxConcurrency": 5,
    "outputFieldName": "structuredOutput",
    "includeInput": true
  }
}
```

### 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

Sends a prompt to a language model and returns a response conforming to a defined JSON schema. Use when you need the LLM to produce structured, parseable data rather than free text — extracting entities, generating structured records, or classification with defined fields. Produces one item per input containing the schema-validated JSON response.