Skip to main content
POST
/
v1
/
swarm
/
batch
/
completions
Execute Batch Swarm Completions
curl --request POST \
  --url https://api.swarms.world/v1/swarm/batch/completions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
[
  {
    "name": "<string>",
    "description": "<string>",
    "agents": [
      {
        "agent_name": "<string>",
        "description": "<string>",
        "system_prompt": "<string>",
        "marketplace_prompt_id": "<string>",
        "model_name": "gpt-4.1",
        "auto_generate_prompt": false,
        "max_tokens": 8192,
        "temperature": 123,
        "role": "worker",
        "max_loops": 1,
        "tools_list_dictionary": [
          {}
        ],
        "selected_tools": "<string>",
        "mcp_url": "<string>",
        "streaming_on": false,
        "llm_args": {},
        "dynamic_temperature_enabled": true,
        "mcp_config": {
          "type": "mcp",
          "url": "http://localhost:8000/mcp",
          "tool_configurations": {},
          "authorization_token": "<string>",
          "transport": "streamable_http",
          "headers": {},
          "timeout": 10
        },
        "mcp_configs": {
          "connections": [
            {
              "type": "mcp",
              "url": "http://localhost:8000/mcp",
              "tool_configurations": {},
              "authorization_token": "<string>",
              "transport": "streamable_http",
              "headers": {},
              "timeout": 10
            }
          ]
        },
        "tool_call_summary": true,
        "reasoning_effort": "low",
        "thinking_tokens": 123,
        "reasoning_enabled": false,
        "publish_to_marketplace": false,
        "use_cases": [
          {}
        ],
        "tags": [
          "<string>"
        ],
        "capabilities": [
          "<string>"
        ],
        "category": "<string>",
        "is_free": true,
        "price_usd": 123,
        "handoffs": [
          "<unknown>"
        ]
      }
    ],
    "max_loops": 1,
    "rearrange_flow": "<string>",
    "task": "<string>",
    "img": "<string>",
    "tasks": [
      "<string>"
    ],
    "messages": [
      {}
    ],
    "stream": false,
    "heavy_swarm_question_agent_model_name": "gpt-4.1",
    "heavy_swarm_worker_model_name": "claude-sonnet-4-20250514",
    "heavy_swarm_variant": "default",
    "council_judge_model_name": "gpt-5.4",
    "chairman_model": "gpt-5.1",
    "multi_agent_collab_prompt": true,
    "heavy_swarm_max_loops": 1,
    "list_all_agents": false
  }
]
'
[
  {}
]

Headers

​
x-api-key
string
required

Body

application/json
​
name
string | null

The name of the swarm, which serves as an identifier for the group of agents and their collective task.

Maximum string length: 100
​
description
string | null

A comprehensive description of the swarm's objectives, capabilities, and intended outcomes.

​
agents
AgentSpec · object[] | null

A list of agents or specifications that define the agents participating in the swarm.

​
max_loops
integer | null
default:1

The maximum number of execution loops allowed for the swarm, enabling repeated processing if needed.

​
swarm_type
enum<string> | null

The classification of the swarm, indicating its operational style and methodology.

Available options:
AgentRearrange,
MixtureOfAgents,
SequentialWorkflow,
ConcurrentWorkflow,
GroupChat,
MultiAgentRouter,
AutoSwarmBuilder,
HierarchicalSwarm,
auto,
MajorityVoting,
CouncilAsAJudge,
HeavySwarm,
BatchedGridWorkflow,
LLMCouncil,
DebateWithJudge,
RoundRobin,
PlannerWorkerSwarm
​
rearrange_flow
string | null

Instructions on how to rearrange the flow of tasks among agents, if applicable.

​
task
string | null

The specific task or objective that the swarm is designed to accomplish.

​
img
string | null

An optional image URL that may be associated with the swarm's task or representation.

​
tasks
string[] | null

A list of tasks that the swarm should complete.

​
messages
object
​
stream
boolean | null
default:false

A flag indicating whether the swarm should stream its output.

​
heavy_swarm_question_agent_model_name
string | null
default:gpt-4.1

The model name to use for the question agent in the heavy swarm.

​
heavy_swarm_worker_model_name
string | null
default:claude-sonnet-4-20250514

The model name to use for the worker agent in the heavy swarm.

​
heavy_swarm_variant
string | null
default:default

For HeavySwarm: which agent variant to run. One of 'default', 'medium', or 'heavy'.

​
council_judge_model_name
string | null
default:gpt-5.4

For CouncilAsAJudge: the model name used by the judge that delivers the final ruling.

​
chairman_model
string | null
default:gpt-5.1

For LLMCouncil: the model name used by the chairman that synthesizes the council's responses.

​
multi_agent_collab_prompt
boolean | null
default:true

Inject the multi-agent collaboration prompt so agents coordinate with one another. Set False to disable.

​
heavy_swarm_max_loops
integer | null
default:1

For HeavySwarm: the maximum number of loops each agent in the heavy swarm may run.

​
list_all_agents
boolean | null
default:false

Whether to list all agents and their descriptions to one another so each agent is aware of the others.

Response

Successful Response