OpenAI Reasoning

Use the GPT-5.x frontier models in extended-reasoning mode for complex multi-step tasks.

Overview

OpenAI Reasoning calls OpenAI frontier models in extended-reasoning mode; the Model dropdown lists the reasoning-capable models currently available to the workspace. These models perform internal chain-of-thought before producing a response and excel at math, coding, logic, and scientific reasoning. The tool calls the OpenAI Responses API (POST /responses) with configurable reasoning effort (low/medium/high). An optional Attachment File ID references a file already uploaded via openai_file_upload and attaches it to the user message as a document or an image, selected by Attachment Type. Returns the model output text along with a reasoning summary and token usage.

Category: AI
Tool Name: openai_reasoning
Version: 1

Appearance: Icon: openai | Color: #10a37f

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires OpenAI credentials. See the Credentials Guide for setup instructions.

Parameters

Parameter	Type	Required	Default	Description
Model	options	No	(current default)	The OpenAI model to invoke in extended-reasoning mode. Pick a specific GPT-5.x version — labels are pinned, not aliased to “latest”.
				Options: the OpenAI reasoning models available to your workspace — pick one from the dropdown.
System Prompt	string	No	You are a helpful assistant.	System-level instructions for the model. Sent as the “instructions” field on the Responses API request. Defaults to a generic helpful-assistant prompt — override per workflow as needed. Supports expressions.
User Message	string	Yes	—	The user message or prompt to send. Falls back to item.json.message or item.json.prompt if empty. Supports expressions.
Attachment File ID	string	No	—	Optional OpenAI file ID (file-…) returned by openai_file_upload. When provided, the file is referenced by ID and attached as a content block on the user message — no re-upload, no binary input needed. Falls back to item.json.attachmentFileId if empty. Supports expressions like {{ $json.fileId }} from an upstream openai_file_upload node.
Attachment Type	options	No	document	How the model should interpret the attached file. Only used when Attachment File ID is set.
				Options: document (PDF / text / code / CSV / structured file), image (jpg / png / gif / webp)
Reasoning Effort	options	No	medium	How much reasoning effort the model should spend.
				Options: low (fastest responses, lowest cost), medium (balanced), high (best quality, higher cost and latency)
Options	collection	No	{}	Optional response settings — add only the fields you need.
— Max Output Tokens	number	No	16384	Maximum number of tokens in the model response.
— Response Field Name	string	No	response	The output field name where the model response text will be stored.
Include Input	boolean	No	false	Whether to include the original input item fields in the output.
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

One output item per input item. The answer text lands on the field named by Response Field Name (response by default), with the reasoning summary, model and usage beside it. The rest of the input item JSON is dropped unless Include Input is on; binary data on the input item is forwarded unchanged.

{
  "response": "The model's answer",
  "reasoning": [],
  "model": "the model that produced the answer",
  "usage": { "input_tokens": 512, "output_tokens": 2048 }
}

• reasoning is the summary the model chose to expose about its internal reasoning. It is often empty — treat it as optional colour, never as the answer.
• usage is the token accounting returned by the API. Reasoning tokens are billed as output tokens, so a high Reasoning Effort raises cost even when the visible answer is short.

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

Usage Examples

• Solve a complex math problem step by step
• Analyze code for bugs using chain-of-thought reasoning
• Reason through a multi-step logic puzzle
• Generate a detailed analysis of a scientific paper
• Solve a competitive programming problem

Example Configuration

Quick, low-cost reasoning with the defaults:

{
  "type": "openai_reasoning",
  "parameters": {
    "userMessage": "{{ $json.question }}",
    "reasoningEffort": "low"
  }
}

Deep analysis with explicit instructions and the input preserved:

{
  "type": "openai_reasoning",
  "parameters": {
    "systemPrompt": "You are a senior engineer. Work through the problem carefully before answering.",
    "userMessage": "Find the race condition in this code and explain the fix:\n{{ $json.code }}",
    "reasoningEffort": "high",
    "includeInput": true,
    "maxConcurrency": 3,
    "options": {
      "maxOutputTokens": 32768,
      "responseFieldName": "analysis"
    }
  }
}

Reason over a file uploaded by an upstream OpenAI File Upload node:

{
  "type": "openai_reasoning",
  "parameters": {
    "userMessage": "Check this spreadsheet for accounting errors and list them.",
    "attachmentFileId": "{{ $json.fileId }}",
    "attachmentType": "document",
    "reasoningEffort": "medium"
  }
}

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

OpenAI Reasoning calls an OpenAI frontier model — whichever option is picked in the Model dropdown — via the OpenAI Responses API in extended-reasoning mode, applying configurable internal chain-of-thought before generating a response. Set Attachment File ID to a file-… id from openai_file_upload to reason over an uploaded document or image. Use it when a workflow step demands complex multi-step problem solving such as mathematical proofs, advanced code generation, logic puzzles, or scientific analysis where standard chat models underperform. The tool outputs response text, a reasoning summary, and token usage statistics through the main channel, routing failures to the error channel.