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

# Execute Reasoning Agent Completion

`POST /v1/reasoning-agent/completions`

## Request

- Base URL: `https://api.swarms.world`
- URL: `https://api.swarms.world/v1/reasoning-agent/completions`
- Auth: none declared. Required headers: `x-api-key`

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: How many independent answers self-consistency and consistency-agent generate before aggregating; each one sends the prompt again and is billed for it. Between 1 and 2000.
  - `output_type` 'list' | 'dict' | 'dictionary' | 'string' | 'str' | 'final' | 'last' | 'json' | 'all' | 'yaml' | '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-10-31** `3e13975ede3d`: 1 breaking, 2 warning
  - request property `num_samples` list-of-types was narrowed by removing types `null` from media type `application/json`
  - the `num_samples` request property's max was set to `2000.00`
  - the `num_samples` request property's min was set to `1.00`
- **2026-10-16** `500c79520e41`: 3 breaking, 3 warning, 17 info
  - request property `swarm_type` was restricted to a list of enum values
  - removed the enum value `xml` of the request property `output_type/anyOf[subschema #1]/`
  - request property `swarm_type` list-of-types was narrowed by removing types `null` from media type `application/json`
  - the `max_loops/anyOf[subschema #1]/` request property's max was set to `50.00`
  - …19 more

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

---

[API](https://skmtc.dev/the-swarm-corporation/apis/swarms-api.md) - [All operations](https://skmtc.dev/the-swarm-corporation/apis/swarms-api/llms.txt) - [OpenAPI document](https://skmtc.dev/the-swarm-corporation/apis/swarms-api/revisions/fca99f497199?raw)