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 thex-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 withoutswarm_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
Architecture-Specific Parameters
These only take effect for their correspondingswarm_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 inagents 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
Marketplace Publishing
Set when you want the agent listed on the Swarms Marketplace as a side effect of the run.MCPConnection
Passed asmcp_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 interactiveauthorization_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.
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.
tasks (an array of task strings, run one after another via SwarmRouter.batch_run) instead of a single task echoes them back:
Errors
HTTPValidationError
A422 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.
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
- Python
- JavaScript
- Shell (curl)
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
Setstream: true to receive output as it is produced rather than waiting for the full run.
Related Resources
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