---
title: "Execute Reasoning Agent Completion"
method: POST
path: "/v1/reasoning-agent/completions"
tags: ["Reasoning Agents"]
---

# Execute Reasoning Agent Completion

`POST /v1/reasoning-agent/completions`

Execute a reasoning agent with advanced cognitive capabilities for complex problem-solving tasks. This is a premium-only feature.

## Headers

- `x-api-key` string, required

## Request body

- ReasoningAgentSpec
  - `agent_name` string, nullable — The unique name assigned to the reasoning agent.
  - `description` string, nullable — A detailed explanation of the reasoning agent's purpose and capabilities.
  - `model_name` string, nullable — The name of the AI model that the reasoning agent will utilize.
  - `system_prompt` string, nullable — The initial instruction or context provided to the reasoning agent.
  - `max_loops` integer, nullable — The maximum number of times the reasoning agent is allowed to repeat its task. At most 50.
  - `swarm_type` 'AgentJudge' | 'ReflexionAgent' | 'self-consistency' | 'consistency-agent' — The type of reasoning agent to run: AgentJudge, ReflexionAgent, self-consistency or consistency-agent.
  - `num_samples` integer, nullable — The number of samples to generate for the reasoning agent.
  - `output_type` 'list' | 'dict' | 'dictionary' | 'string' | 'str' | 'final' | 'last' | 'json' | 'all' | 'yaml' | 'xml' | 'dict-all-except-first' | 'str-all-except-first' | 'basemodel' | 'dict-final' | 'list-final', nullable — The type of output format for the reasoning agent.
  - `memory_capacity` integer, nullable — The memory capacity for a ReflexionAgent.
  - `task` string, nullable — The task to be completed by the reasoning agent.

## Response `200`

Successful Response

- ReasoningAgentCompletionOutput
  - `job_id` string, required — Unique identifier for the reasoning agent run.
  - `status` string — Status of the reasoning agent run.
  - `outputs` unknown, required
  - `timestamp` string, required — ISO-formatted timestamp of when the run was executed.
  - `agent_name` string, required — Name of the agent.
  - `agent_type` string, required — Type of the agent (swarm type).
  - `agent_id` string, required — Unique identifier for the agent instance.
  - `usage` object, required — Usage statistics: input, output and total tokens plus the run's total_cost (a float, so this cannot be Dict[str, int]).

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-25** `7bb777a831f3` — 2 breaking, 1 warning, 6 info
  - request property `swarm_type` was restricted to a list of enum values
  - request property `swarm_type` list-of-types was narrowed by removing types `null` from media type `application/json`
  - removed the request property `num_knowledge_items`
  - the `model_name` request property default value changed from `claude-sonnet-4-20250514` to `claude-sonnet-5`
  - …5 more
- **2026-08-22** `b7b92eb482fe` — 1 breaking, 1 warning
  - the `max_loops/anyOf[subschema #1]/` request property's max was decreased to `50.00`
  - the `max_loops/anyOf[subschema #1]/` request property's min was set to `1.00`
- **2026-08-20** `35f4c5ec5bfd` — 1 warning
  - the `max_loops/anyOf[subschema #1]/` request property's max was set to `100.00`

[Change history](https://skmtc.dev/swarms/apis/swarms-api/changes/v1/reasoning-agent/completions/post.md)

---

[API](https://skmtc.dev/swarms/apis/swarms-api.md) · [All operations](https://skmtc.dev/swarms/apis/swarms-api/llms.txt) · [OpenAPI document](https://skmtc.dev/swarms/apis/swarms-api/revisions/045f2bf862b9?raw)