---
title: "Execute Swarm Completion"
method: POST
path: "/v1/swarm/completions"
tags: ["Swarms"]
---

# Execute Swarm Completion

`POST /v1/swarm/completions`

Execute a swarm completion with the specified task. Supports both standard and streaming responses.

## Headers

- `x-api-key` string, required

## Request body

- SwarmSpec
  - `name` string, nullable — The name of the swarm, which serves as an identifier for the group of agents and their collective task.
  - `description` string, nullable — A comprehensive description of the swarm's objectives, capabilities, and intended outcomes.
  - `agents` AgentSpecInput[], nullable — A list of agents or specifications that define the agents participating in the swarm.
    - `agent_name` string, nullable — The unique name assigned to the agent, which identifies its role and functionality within the swarm.
    - `description` string, nullable — A detailed explanation of the agent's purpose, capabilities, and any specific tasks it is designed to perform.
    - `system_prompt` string, nullable — The initial instruction or context provided to the agent, guiding its behavior and responses during execution.
    - `marketplace_prompt_id` string, nullable — The ID of a prompt from the Swarms marketplace to use as the system prompt. If provided, the prompt will be automatically retrieved from the marketplace.
    - `model_name` string, nullable — The name of the AI model that the agent will utilize for processing tasks and generating outputs. For example: gpt-4o, gpt-4.1, openai/o3-mini
    - `fallback_models` string[], nullable — An ordered list of models to try if the primary model errors: the request is retried with the next model on failure. If set while model_name is omitted, the first entry becomes the primary model. Example: ['gpt-4.1', 'gpt-5.4'].
    - `fallback_model_name` string, nullable — A single fallback model to try if the primary model fails, tried after any `fallback_models`. Example: 'gpt-4.1'.
    - `auto_generate_prompt` boolean, nullable — A flag indicating whether the agent should automatically create prompts based on the task requirements.
    - `max_tokens` integer, nullable — The maximum number of tokens that the agent is allowed to generate in its responses, limiting output length.
    - `temperature` number, nullable — A parameter that controls the randomness of the agent's output; lower values result in more deterministic responses. Accepted range: 0 to 2. If omitted, no temperature is sent to the model (the provider's own default applies).
    - `role` string, nullable — The designated role of the agent within the swarm, which influences its behavior and interaction with other agents.
    - `max_loops` union — Maximum number of iterations the agent can perform for its task. Accepts an integer for a fixed count, or 'auto' to allow the system to determine the necessary number based on the task's complexity.
      - integer
      - string
    - `tools_list_dictionary` object[], nullable — A dictionary of tools that the agent can use to complete its task.
    - `selected_tools` union — Tools to enable for the autonomous looper when max_loops='auto'. Pass a list of tool names to restrict which tools the agent can use, or omit to allow all safe defaults. Available tools: create_plan, think, subtask_done, complete_task, respond_to_user, create_file, update_file, read_file, list_directory, delete_file, create_sub_agent, assign_task. Note: run_bash is not permitted.
      - string
      - string[]
    - `mcp_url` string, nullable — The URL of the MCP server that the agent can use to complete its task.
    - `streaming_on` boolean, nullable — A flag indicating whether the agent should stream its output.
    - `llm_args` object, nullable — Additional arguments to pass to the LLM such as top_p, frequency_penalty, presence_penalty, etc.
    - `top_p` number, nullable — The top_p parameter to pass to the LLM.
    - `dynamic_temperature_enabled` boolean, nullable — A flag indicating whether the agent should dynamically adjust its temperature based on the task.
    - `mcp_config` MCPConnection
      - `type` string, nullable — The type of connection, defaults to 'mcp'
      - `url` string, nullable — The URL endpoint for the MCP server
      - `name` string, nullable — Human readable name for the server, used in logs and tool routing
      - `tool_configurations` object, nullable — Dictionary containing configuration settings for MCP tools
      - `authorization_token` string, nullable — Bearer token for accessing the MCP server
      - `api_key` string, nullable — API key for the MCP server. Sent using api_key_header/api_key_prefix.
      - `api_key_header` string — Header used to send the API key, e.g. 'Authorization' or 'X-API-Key'.
      - `api_key_prefix` string, nullable — Prefix prepended to the API key value. Set to None/'' for raw keys.
      - `auth_type` 'none' | 'api_key' | 'bearer' | 'oauth' | 'custom', nullable — Explicit auth mode. Inferred from the other fields when omitted.
      - `oauth` MCPOAuthConfig — OAuth 2.1 configuration for an MCP server. Three flavours are supported: 1. ``grant_type="authorization_code"`` (default) — the interactive browser flow described by the MCP authorization spec. PKCE and RFC 7591 dynamic client registration are handled by the MCP SDK, so ``client_id`` is optional. Tokens are cached on disk so the browser prompt only happens once. 2. ``grant_type="client_credentials"`` — a headless machine-to-machine flow. Requires ``client_id``/``client_secret``. The token endpoint is discovered from the server's ``/.well-known/oauth-authorization-server`` metadata unless ``token_url`` is given. 3. ``access_token=...`` — a token you already obtained elsewhere. No flow is run; the token is simply sent as a bearer credential. Any string field may use ``"env:MY_VAR"`` or ``"${MY_VAR}"`` to read the value from the environment instead of hardcoding a secret.
        - `grant_type` 'authorization_code' | 'client_credentials' — OAuth grant to use when no static access_token is supplied.
        - `client_id` string, nullable — OAuth client id. Optional for authorization_code when the server supports dynamic client registration.
        - `client_secret` string, nullable — OAuth client secret. Required for client_credentials.
        - `scopes` string[], nullable — Scopes to request, e.g. ['mcp:tools', 'offline_access'].
        - `redirect_uri` string — Loopback redirect URI used to capture the authorization code.
        - `client_name` string — Client name sent during dynamic client registration.
        - `client_uri` string, nullable — Client homepage sent during dynamic client registration.
        - `authorization_url` string, nullable — Explicit authorization endpoint. Discovered automatically when omitted.
        - `token_url` string, nullable — Explicit token endpoint. Discovered automatically when omitted.
        - `access_token` string, nullable — Pre-obtained access token. When set, no OAuth flow is performed.
        - `refresh_token` string, nullable — Pre-obtained refresh token, paired with access_token.
        - `token_storage_path` string, nullable — File used to cache OAuth tokens. Defaults to ~/.swarms/mcp_auth/<server>.json.
        - `use_token_cache` boolean — Persist tokens to disk so the browser flow is only run once.
        - `open_browser` boolean — Open the system browser for the authorization step. When False the URL is logged instead.
        - `callback_timeout` integer — Seconds to wait for the user to complete the browser flow.
      - `transport` string, nullable — Transport protocol: 'streamable_http', 'sse', 'stdio', or 'auto'
      - `headers` object, nullable — Headers to send to the MCP server
      - `timeout` integer, nullable — Request timeout for the MCP server
      - `sse_read_timeout` integer, nullable — How long to wait for streamed events before giving up
      - `tool_timeout` integer, nullable — How long a single tool call may run before timing out. Separate from `timeout`, which bounds HTTP requests.
      - `command` string, nullable — Executable to launch for the 'stdio' transport
      - `args` string[], nullable — Arguments passed to the 'stdio' command
      - `env` object, nullable — Environment variables for the 'stdio' command
    - `mcp_configs` MultipleMCPConnections
      - `connections` MCPConnection[], required — List of MCP connections
        - `type` string, nullable — The type of connection, defaults to 'mcp'
        - `url` string, nullable — The URL endpoint for the MCP server
        - `name` string, nullable — Human readable name for the server, used in logs and tool routing
        - `tool_configurations` object, nullable — Dictionary containing configuration settings for MCP tools
        - `authorization_token` string, nullable — Bearer token for accessing the MCP server
        - `api_key` string, nullable — API key for the MCP server. Sent using api_key_header/api_key_prefix.
        - `api_key_header` string — Header used to send the API key, e.g. 'Authorization' or 'X-API-Key'.
        - `api_key_prefix` string, nullable — Prefix prepended to the API key value. Set to None/'' for raw keys.
        - `auth_type` 'none' | 'api_key' | 'bearer' | 'oauth' | 'custom', nullable — Explicit auth mode. Inferred from the other fields when omitted.
        - `oauth` MCPOAuthConfig — OAuth 2.1 configuration for an MCP server. Three flavours are supported: 1. ``grant_type="authorization_code"`` (default) — the interactive browser flow described by the MCP authorization spec. PKCE and RFC 7591 dynamic client registration are handled by the MCP SDK, so ``client_id`` is optional. Tokens are cached on disk so the browser prompt only happens once. 2. ``grant_type="client_credentials"`` — a headless machine-to-machine flow. Requires ``client_id``/``client_secret``. The token endpoint is discovered from the server's ``/.well-known/oauth-authorization-server`` metadata unless ``token_url`` is given. 3. ``access_token=...`` — a token you already obtained elsewhere. No flow is run; the token is simply sent as a bearer credential. Any string field may use ``"env:MY_VAR"`` or ``"${MY_VAR}"`` to read the value from the environment instead of hardcoding a secret.
          - `grant_type` 'authorization_code' | 'client_credentials' — OAuth grant to use when no static access_token is supplied.
          - `client_id` string, nullable — OAuth client id. Optional for authorization_code when the server supports dynamic client registration.
          - `client_secret` string, nullable — OAuth client secret. Required for client_credentials.
          - `scopes` string[], nullable — Scopes to request, e.g. ['mcp:tools', 'offline_access'].
          - `redirect_uri` string — Loopback redirect URI used to capture the authorization code.
          - `client_name` string — Client name sent during dynamic client registration.
          - `client_uri` string, nullable — Client homepage sent during dynamic client registration.
          - `authorization_url` string, nullable — Explicit authorization endpoint. Discovered automatically when omitted.
          - `token_url` string, nullable — Explicit token endpoint. Discovered automatically when omitted.
          - `access_token` string, nullable — Pre-obtained access token. When set, no OAuth flow is performed.
          - `refresh_token` string, nullable — Pre-obtained refresh token, paired with access_token.
          - `token_storage_path` string, nullable — File used to cache OAuth tokens. Defaults to ~/.swarms/mcp_auth/<server>.json.
          - `use_token_cache` boolean — Persist tokens to disk so the browser flow is only run once.
          - `open_browser` boolean — Open the system browser for the authorization step. When False the URL is logged instead.
          - `callback_timeout` integer — Seconds to wait for the user to complete the browser flow.
        - `transport` string, nullable — Transport protocol: 'streamable_http', 'sse', 'stdio', or 'auto'
        - `headers` object, nullable — Headers to send to the MCP server
        - `timeout` integer, nullable — Request timeout for the MCP server
        - `sse_read_timeout` integer, nullable — How long to wait for streamed events before giving up
        - `tool_timeout` integer, nullable — How long a single tool call may run before timing out. Separate from `timeout`, which bounds HTTP requests.
        - `command` string, nullable — Executable to launch for the 'stdio' transport
        - `args` string[], nullable — Arguments passed to the 'stdio' command
        - `env` object, nullable — Environment variables for the 'stdio' command
    - `tool_call_summary` boolean, nullable — A parameter enabling an agent to summarize tool calls.
    - `reasoning_effort` 'minimal' | 'low' | 'medium' | 'high' | 'none' | 'xhigh' | 'ultra' | 'max', nullable — How much effort the agent puts into reasoning. Accepted values, tracking the reasoning levels the installed litellm advertises: 'minimal', 'low', 'medium', 'high', 'none', 'xhigh', 'ultra', 'max'. 'max' is the top tier (deepest reasoning) and no beta header is required. At 'xhigh' and above, pair with a large max_tokens so the model has room to think and answer.
    - `thinking_tokens` integer, nullable — The number of tokens to use for thinking.
    - `reasoning_enabled` boolean, nullable — A parameter enabling an agent to use reasoning.
    - `publish_to_marketplace` boolean, nullable — A flag indicating whether to publish this agent to the Swarms marketplace.
    - `use_cases` object[], nullable — A list of use case dictionaries with 'title' and 'description' keys. Required when publish_to_marketplace is True.
    - `tags` string[], nullable — A list of searchable tags/keywords for the marketplace (e.g., ['finance', 'analysis']).
    - `capabilities` string[], nullable — A list of agent capabilities or features (e.g., ['trend-analysis', 'risk-assessment']).
    - `category` string, nullable — The marketplace category for the agent (e.g., 'research', 'content', 'coding', 'finance', 'healthcare', 'education', 'legal').
    - `is_free` boolean, nullable — A flag indicating whether the agent is free to use in the marketplace.
    - `price_usd` number, nullable — The price in USD for using this agent in the marketplace (if not free).
    - `handoffs` AgentSpecInput[], nullable — A list of agent specifications that this agent can hand off tasks to. These agents will be created and passed to the agent's handoffs parameter.
  - `max_loops` integer, nullable — The maximum number of execution loops allowed for the swarm, enabling repeated processing if needed.
  - `swarm_type` 'AgentRearrange' | 'MixtureOfAgents' | 'SequentialWorkflow' | 'ConcurrentWorkflow' | 'GroupChat' | 'MultiAgentRouter' | 'HierarchicalSwarm' | 'auto' | 'MajorityVoting' | 'CouncilAsAJudge' | 'HeavySwarm' | 'BatchedGridWorkflow' | 'LLMCouncil' | 'DebateWithJudge' | 'RoundRobin' | 'PlannerWorkerSwarm', nullable — The classification of the swarm, indicating its operational style and methodology.
  - `rearrange_flow` string, nullable — Instructions on how to rearrange the flow of tasks among agents, if applicable.
  - `task` string, nullable — The specific task or objective that the swarm is designed to accomplish.
  - `img` string, nullable — An optional image URL that may be associated with the swarm's task or representation.
  - `tasks` string[], nullable — A list of tasks that the swarm should complete.
  - `messages` union — A list of messages that the swarm should complete.
    - object[]
    - object
  - `stream` boolean, nullable — A flag indicating whether the swarm should stream its output.
  - `heavy_swarm_question_agent_model_name` string, nullable — The model name to use for the question agent in the heavy swarm.
  - `heavy_swarm_worker_model_name` string, nullable — The model name to use for the worker agent in the heavy swarm.
  - `heavy_swarm_variant` 'default' | 'medium' | 'heavy', nullable — For HeavySwarm: which agent variant to run. One of 'default', 'medium', or 'heavy'.
  - `council_judge_model_name` string, nullable — For CouncilAsAJudge: the model name used by the judge that delivers the final ruling.
  - `chairman_model` string, nullable — For LLMCouncil: the model name used by the chairman that synthesizes the council's responses.
  - `multi_agent_collab_prompt` boolean, nullable — Inject the multi-agent collaboration prompt so agents coordinate with one another. Set False to disable.
  - `heavy_swarm_max_loops` integer, nullable — For HeavySwarm: the maximum number of loops each agent in the heavy swarm may run.
  - `list_all_agents` boolean, nullable — Whether to list all agents and their descriptions to one another so each agent is aware of the others.
  - `director_model_name` string, nullable — The model name to use for the director/overseer agent (if any). For HierarchicalSwarm, this is the model name of the director.
  - `director_settings` object, nullable — Optional settings or hyperparameters for the director agent. For HierarchicalSwarm, this is the settings of the director. You can set temperature, top_p, max_tokens, etc.

## Response `200`

Successful Response

- SwarmCompletion
  - `job_id` string, nullable, required — The unique identifier for the swarm completion.
  - `status` string, nullable, required — The status of the swarm completion.
  - `swarm_name` string, nullable, required — The name of the swarm.
  - `description` string, nullable, required — The description of the swarm.
  - `swarm_type` string, nullable, required — The type of the swarm.
  - `output` unknown, required
  - `number_of_agents` integer, nullable, required — The number of agents in the swarm.
  - `execution_time` number, nullable, required — The execution time of the swarm.
  - `usage` object, nullable, required — The usage of the swarm.

## 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/versions/2575bd7539ca/schema)