Reasoning

Some models — particularly those trained for complex problem-solving — can spend additional compute on an internal reasoning pass before producing their final answer. The Responses API exposes this through a reasoning parameter.

Enabling Reasoning#

Pass a reasoning object in your request to activate extended thinking:

{
  "model": "anthropic/claude-opus-4.8",
  "input": "Prove that the square root of 2 is irrational.",
  "reasoning": {
    "effort": "high"
  }
}

Effort Levels#

Reasoning Output#

When reasoning is enabled, the response output array may include a reasoning item before the final message:

{
  "output": [
    {
      "type": "reasoning",
      "id": "rs_abc123",
      "encrypted_content": "gAAAAABotI9-FK1Pbh...",
      "summary": ["First, assume √2 is a fraction in lowest terms", "Then both parts must be even — a contradiction"]
    },
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "..." }]
    }
  ]
}

The reasoning item contains a summary of the model's internal deliberation, and, where the model gives one, its encrypted reasoning. The API is stateless: to carry a reasoning model's work into the next turn, send the reasoning item back in input with the rest of the conversation. The reasoning tokens are counted in usage.output_tokens_details.reasoning_tokens.

Billing#

Reasoning tokens are billed the same as output tokens. A high effort request on a capable model can generate several thousand reasoning tokens before the visible answer, so monitor your usage field. See Reasoning Tokens for cost guidance and controls.

Model Compatibility#

Only models that support extended thinking honor the reasoning parameter. A model that does lists reasoning in its supported_parameters, read at GET /v1/models.