---
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.
  - `swarm_type` 'reasoning-duo' | 'self-consistency' | 'ire' | 'reasoning-agent' | 'consistency-agent' | 'ire-agent' | 'ReflexionAgent' | 'GKPAgent' | 'AgentJudge', nullable — The type of reasoning swarm to use (e.g., reasoning duo, self-consistency, IRE).
  - `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.
  - `num_knowledge_items` integer, nullable — The number of knowledge items to use for the reasoning agent.
  - `memory_capacity` integer, nullable — The memory capacity for the reasoning agent.
  - `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 — Token usage statistics including input, output, and total tokens.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/swarms/apis/swarms-api.md) · [All operations](https://skmtc.net/swarms/apis/swarms-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/swarms/swarms-api/revisions/2575bd7539ca/schema)