<!-- BusyBot node reference — https://busybot.net/tools/openai-reasoning/ -->

> Node: OpenAI Reasoning (`openai_reasoning`) · Action · v1
> Category: AI · Credentials: OpenAI (`openai`)
> Updated: 2026-08-16

# 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](https://busybot.net/credentials/openai/) 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.

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

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

Deep analysis with explicit instructions and the input preserved:

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

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