/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.
Endpoint
Architecture
The exact internals depend onswarm_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 singleReasoningAgentSpec 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
- Python
- JavaScript
- Shell (curl)
Response
Response Schema
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-consistencyandconsistency-agentbill the prompt (agent_name,description,system_promptandtask) once per sample, so input tokens are the counted prompt tokens ×num_samples, andnum_samples: 5costs about five times the prompt. Output tokens are counted from the returnedoutputs.AgentJudgeandReflexionAgentbill the tokens their internal agents reported for every call they made. AReflexionAgentcalls its actor, evaluator and reflector on each iteration, so a highermax_loopsbills more tokens.
usage reports the billed totals.
Related Resources
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