Reasoning

Reasoning models excel at complex problem-solving tasks that require step-by-step analysis, logical deduction, and structured thinking and solution validation. With Groq inference speed, these types of models can deliver instant reasoning capabilities critical for real-time applications.

Why Speed Matters for Reasoning

Reasoning models are capable of complex decision making with explicit reasoning chains that are part of the token output and used for decision-making, which make low-latency and fast inference essential. Complex problems often require multiple chains of reasoning tokens where each step build on previous results. Low latency compounds benefits across reasoning chains and shaves off minutes of reasoning to a response in seconds.

Supported Models

Reasoning Format

Groq API supports explicit reasoning formats through the reasoning_format parameter, giving you fine-grained control over how the model's reasoning process is presented. This is particularly valuable for valid JSON outputs, debugging, and understanding the model's decision-making process.

Note: The format defaults to raw or parsed when JSON mode or tool use are enabled as those modes do not support raw. If reasoning is explicitly set to raw with JSON mode or tool use enabled, we will return a 400 error.

Options for Reasoning Format

Including Reasoning in the Response

You can also control whether reasoning is included in the response by setting the include_reasoning parameter.

Note: The include_reasoning parameter cannot be used together with reasoning_format. These parameters are mutually exclusive.

Reasoning Effort

Options for Reasoning Effort (Qwen 3 32B)

The reasoning_effort parameter controls the level of effort the model will put into reasoning. This is only supported by Qwen 3 32B.

Options for Reasoning Effort (GPT-OSS)

The reasoning_effort parameter controls the level of effort the model will put into reasoning. This is only supported by GPT-OSS 20B and GPT-OSS 120B.

Quick Start

Get started with reasoning models using this basic example that demonstrates how to make a simple API call for complex problem-solving tasks.

import Groq from 'groq-sdk';

const client = new Groq();
const completion = await client.chat.completions.create({
    model: "openai/gpt-oss-20b",
    messages: [
        {
            role: "user",
            content: "How many r's are in the word strawberry?"
        }
    ],
    temperature: 0.6,
    max_completion_tokens: 1024,
    top_p: 0.95,
    stream: true
});

for await (const chunk of completion) {
    process.stdout.write(chunk.choices[0].delta.content || "");
}

Quick Start with Tool Use

This example shows how to combine reasoning models with function calling to create intelligent agents that can perform actions while explaining their thought process.

curl https://api.groq.com//openai/v1/chat/completions -s \
  -H "authorization: bearer $GROQ_API_KEY" \
  -d '{
    "model": "openai/gpt-oss-20b",
    "messages": [
        {
            "role": "user",
            "content": "What is the weather like in Paris today?"
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "Get current temperature for a given location.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "City and country e.g. Bogotá, Colombia"
                        }
                    },
                    "required": [
                        "location"
                    ],
                    "additionalProperties": false
                },
                "strict": true
            }
        }
    ]}'

Recommended Configuration Parameters

Accessing Reasoning Content

Accessing the reasoning content in the response is dependent on the model and the reasoning format you are using. See the examples below for more details and refer to the Reasoning Format section for more information.

Non-GPT-OSS Models

import { Groq } from 'groq-sdk';

const groq = new Groq();

const chatCompletion = await groq.chat.completions.create({
  "messages": [
    {
      "role": "user",
      "content": "How do airplanes fly? Be concise."
    }
  ],
  "model": "qwen/qwen3-32b",
  "stream": false,
  "reasoning_format": "raw"
});

console.log(chatCompletion.choices[0].message);

{
  "role": "assistant",
  "content": "<think>Okay, the user is asking how airplanes fly and wants a concise answer. Let me start by recalling the basics of flight mechanics. First, lift is essential. Airplanes generate lift with their wings. The shape of the wing, or airfoil, causes air to move faster over the top, creating lower pressure compared to the bottom. This pressure difference lifts the plane. But wait, I should mention Bernoulli's principle here. Also, angle of attack affects lift by directing airflow downward, which pushes the wing up by Newton's third law. Both factors contribute to lift. Thrust is needed to move the plane forward, providing the speed necessary for lift. Engines like jet engines or propellers generate thrust. Drag is the opposing force; the plane must overcome it. Stability and control come into play too—ailerons, rudder, elevator for maneuvers. Wait, the user wants it concise. Maybe I should prioritize the main points: lift due to wings' shape and angle, thrust from engines, and balance forces. Avoid getting too technical with equations but mention the key components. Also, mention that controlled flight involves managing these forces. Let me make sure I'm not missing anything crucial. Maybe lift, thrust, drag, weight—those are the four forces. But since the user wants it brief, I can simplify to the main elements without listing all four forces. Double-check if Bernoulli's principle is accurate here. Some debates exist about its role versus Newton's laws, but a simplified explanation is acceptable here. Also, mention that the engines provide forward motion, which is crucial for sustaining lift. Putting it all together: airplanes fly by generating lift through their wings' design and angle of attack, using engines for thrust to maintain speed, and controlling flight with adjustable surfaces. Should be concise and cover the essentials.</think>Airplanes fly by generating **lift** through the shape of their wings (airfoils), which causes faster airflow over the top and slower air underneath, creating a pressure difference. **Thrust** from engines (or propellers) propels them forward, countering **drag**, while **control surfaces** (ailerons, rudder, elevator) adjust airflow for stability and direction. Lift must overcome **weight** (gravity) to stay aloft."
}

GPT-OSS Models

With openai/gpt-oss-20b and openai/gpt-oss-120b, the reasoning_format parameter is not supported. By default, these models will include reasoning content in the reasoning field of the assistant response. You can also control whether reasoning is included in the response by setting the include_reasoning parameter.

import { Groq } from 'groq-sdk';

const groq = new Groq();

const chatCompletion = await groq.chat.completions.create({
  "messages": [
    {
      "role": "user",
      "content": "How do airplanes fly? Be concise."
    }
  ],
  "model": "openai/gpt-oss-20b",
  "stream": false,
  "include_reasoning": false
});

console.log(chatCompletion.choices[0].message);

{
  "role": "assistant",
  "content": "Airplanes fly because their wings are shaped like airfoils that slice the air and produce lift: air travels faster over the curved upper surface (Bernoulli principle) and/or is deflected downward, creating an upward lift force that exceeds gravity. Engines provide thrust to overcome drag and keep the aircraft moving forward, so lift can keep it aloft. Control surfaces then balance lift, weight, thrust, and drag to steer and maintain flight."
}

Optimizing Performance

Temperature and Token Management

The model performs best with temperature settings between 0.5-0.7, with lower values (closer to 0.5) producing more consistent mathematical proofs and higher values allowing for more creative problem-solving approaches. Monitor and adjust your token usage based on the complexity of your reasoning tasks - while the default max_completion_tokens is 1024, complex proofs may require higher limits.

Prompt Engineering

To ensure accurate, step-by-step reasoning while maintaining high performance:

• DeepSeek-R1 works best when all instructions are included directly in user messages rather than system prompts.
• Structure your prompts to request explicit validation steps and intermediate calculations.
• Avoid few-shot prompting and go for zero-shot prompting only.