Skip to main content
POST /v1/swarm/completions is the primary endpoint of the Swarms API. One request describes a whole multi-agent system — the roster, the architecture that coordinates it, and the task — and the response returns the swarm’s output along with timing and usage. This page is the complete field-by-field reference. For a conceptual introduction, start with Multi-Agent Overview; for guidance on picking a topology, see Available Architectures.

Endpoint

Authentication

Every request requires your API key in the x-api-key header. Get one from the API Keys page.
The batch variant, /v1/swarm/batch/completions, accepts an array of these same SwarmSpec objects (at most 50 per request) and is premium-gated. The single endpoint documented here is not.

Request Body: SwarmSpec

Every field is optional at the schema level, but the server rejects a request without swarm_type, without agents (except for HeavySwarm), or without a task, tasks or messages with a 400. In practice you always send agents, swarm_type, and a task.

Core Parameters

agents accepts up to 2000 entries and max_loops is capped at 50. Exceeding either returns a 422 validation error before any work is billed.

Architecture-Specific Parameters

These only take effect for their corresponding swarm_type. Sending them with a different architecture is harmless but has no effect.

Swarm Types

swarm_type accepts one of the following 14 values (this is the live list returned by GET /v1/swarms/available; see Available Architectures for full metadata on each):
"auto" and "SpreadSheetSwarm" are not in the enum and are rejected with a 422 (literal_error) even though older documentation may reference them. BatchedGridWorkflow and GraphWorkflow are not swarm_type values at all — they are separate, premium-only endpoints: /v1/batched-grid-workflow/completions and /v1/graph-workflow/completions.

AgentSpec

Each entry in agents is an AgentSpec. Every field is optional.

Identity and Model

Generation Controls

Looping and Tools

selected_tools accepts: create_plan, think, subtask_done, complete_task, respond_to_user, create_sub_agent, assign_task. An unknown name returns a 422. Shell and file tools (run_bash, create_file, update_file, read_file, list_directory, delete_file) are not permitted and return a 422.

Reasoning

At xhigh and above, pair reasoning_effort with a large max_tokens so the model has room to both think and answer. A low max_tokens at high effort produces truncated or empty output.

Marketplace Publishing

Set when you want the agent listed on the Swarms Marketplace as a side effect of the run.

MCPConnection

Passed as mcp_config on an AgentSpec, or as an entry of mcp_configs or mcp_urls. Accepts additional properties beyond those listed. The server url must start with https://; anything else returns a 422.

MCP Authentication

stdio servers are not accepted: a connection with transport: "stdio" or a command returns a 422. Use an https:// server.

MCPOAuthConfig

Three flavors are supported: the interactive authorization_code browser flow (PKCE and dynamic client registration handled for you, so client_id is optional), the headless client_credentials flow, or supplying a pre-obtained access_token so no flow runs at all.
Send MCP credentials as values. A field set to an "env:MY_VAR" or "${MY_VAR}" reference returns a 422, because the server’s environment is not yours to read.

Response: SwarmCompletion

Every field below is always present in a successful response. tasks and messages echo the request’s own values back, and are null when the request did not supply them, as on a plain task-only request.
A run that sets tasks (an array of task strings, run one after another via SwarmRouter.batch_run) instead of a single task echoes them back:
output is untyped in the schema because each architecture returns a different structure — SequentialWorkflow returns an ordered conversation, MajorityVoting returns votes plus a verdict. Branch on swarm_type rather than assuming a fixed shape. All swarm types are executed through a SwarmRouter that always forces output_type="dict" server-side, so output is typically a list of {"role": ..., "content": ...} turns — the order and the meaning of each role depends on the coordination pattern (see each architecture’s page).

Errors

HTTPValidationError

A 422 returns a detail array with one ValidationError per offending field: The API strips Pydantic’s input, ctx and url keys, so the submitted value is never echoed back.
Common causes: max_loops above 50, agents longer than 2000, max_tokens below 1, temperature outside 0–2, a swarm_type outside the enum, or a director_settings key outside the allowed list. AgentRearrange without rearrange_flow returns a 400, not a 422.

Examples

Basic Swarm Completion

Architecture-Specific Parameters

HierarchicalSwarm with a tuned director, and AgentRearrange with an explicit flow:
HeavySwarm builds its own agents internally — pass "agents": []. See HeavySwarm.

Streaming

Set stream: true to receive output as it is produced rather than waiting for the full run.
See Streaming and Swarm Streaming for the event shapes.

Multi-Agent Overview

Conceptual introduction to swarms

Available Architectures

Pick the right topology for your task

Batch Swarm Completions

Run up to 50 swarms in one request

Agent Completions

The single-agent endpoint

Graph Workflow

DAG orchestration on its own endpoint

Pricing

How swarm runs are billed