Skip to main content
The Reasoning Agent Completions endpoint (/v1/reasoning-agent/completions) runs a single task through a specialized reasoning architecture rather than a plain agent loop. Instead of one model call producing one answer, a reasoning agent decomposes, samples, critiques, or debates its way to a result — trading cost and latency for reliability on problems where a single pass is often wrong.
Premium tier required. This endpoint is restricted to Pro, Ultra, and Premium subscribers. Free-tier keys receive a 403 with upgrade instructions. See Premium Endpoints.

Endpoint

Architecture

The exact internals depend on swarm_type — some architectures sample independently and reconcile, others critique and revise in sequence. What they share is that one request produces multiple internal reasoning passes before returning.

ReasoningAgentSpec

The request body is a single ReasoningAgentSpec object.

Reasoning Types

swarm_type accepts the following values:
Any other value, including the removed reasoning-duo, reasoning-agent, ire, ire-agent and GKPAgent, returns 422 before any model call or charge. Call GET /v1/reasoning-agent/types for the live list.

Output Types

output_type is accepted for schema compatibility but ignored by the server: every run returns outputs in dict-all-except-first format. The field still validates against list, dict, dictionary, string, str, final, last, json, all, yaml, dict-all-except-first, str-all-except-first, dict-final and list-final; any other value returns 422.

Quick Start

Response

Response Schema

outputs is deliberately untyped in the schema: each reasoning type returns a different structure. self-consistency and consistency-agent return a list of role/content entries: one whose content is the list of sample answers, then a Majority Voting Agent entry holding the reconciled answer. ReflexionAgent returns its best answer across iterations, and AgentJudge returns its conversation (your task followed by each evaluation round), both as strings. Do not assume a fixed shape — branch on agent_type.

Status Codes

This endpoint is both premium-only and billable, so a request is checked, in order, for: API key presence (401), API key validity (401), credit balance (402), and premium tier (403) — all before the reasoning agent runs. Every error from this pre-flight check is returned in the shape {"error": {"type": ..., "message": ..., "detail": ..., "status_code": ...}}.

When to Use a Reasoning Agent

Reasoning agents cost more than a plain agent call — multiple internal passes means multiple sets of billed tokens. They earn that cost on problems where a single pass is unreliable: Raise num_samples to increase consensus strength on self-consistency; raise max_loops to give ReflexionAgent more revision rounds. Both raise the cost.

Billing

Tokens are billed at the model’s per-token price, with no per-agent fee and no night-time discount. How the tokens are counted depends on the type:
  • self-consistency and consistency-agent bill the prompt (agent_name, description, system_prompt and task) once per sample, so input tokens are the counted prompt tokens × num_samples, and num_samples: 5 costs about five times the prompt. Output tokens are counted from the returned outputs.
  • AgentJudge and ReflexionAgent bill the tokens their internal agents reported for every call they made. A ReflexionAgent calls its actor, evaluator and reflector on each iteration, so a higher max_loops bills more tokens.
usage reports the billed totals.

Reasoning Agent Types

Fetch the live list of reasoning architectures

Reasoning Agents Tutorial

Worked example on a hard analytical problem

Agent Completions

The standard single-agent endpoint

Premium Endpoints

Tier requirements and the 403 error shape