OpenAI Reasoning

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.

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.
Web Search	boolean	No	false	Enable OpenAI’s built-in web search. When on, the model may search the web before answering and returns cited sources in the sources output field.
Search Context Size	options	No	medium	How much web search context to give the model. Only used when Web Search is on. (shown when Web Search is on)
				Options: low (fastest, cheapest, fewer sources), medium (balanced default), high (more sources and detail, slower)
Search User Location	collection	No	{}	Optional approximate user location that biases search results. Leave empty for no localization. (shown when Web Search is on)
— Country	string	No	—	Two-letter ISO 3166-1 alpha-2 country code.
— City	string	No	—	Free-text city name.
— Region	string	No	—	Free-text region or state name.
— Timezone	string	No	—	IANA timezone identifier.
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 },
  "sources": [{ "url": "https://...", "title": "Page title", "snippet": "cited excerpt" }]
}

• 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.
• 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, plus snippet when OpenAI supplies citation offsets.

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

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 uses OpenAI frontier models in extended-reasoning mode to solve complex multi-step problems. It is the right tool when a task requires advanced mathematical, coding, logical, or scientific reasoning that standard chat models cannot adequately handle. The tool produces a response text, a reasoning summary, and token usage statistics.