Skip to main content
POST
Execute Swarm Completion

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. At most 2000. GroupChat needs at least 2, and DebateWithJudge exactly 3 in the order pro, con, judge.

Maximum array length: 2000
max_loops
integer | null
default:1

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

Required range: x <= 50
swarm_type
enum<string> | null

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

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

Required for AgentRearrange: agent names joined by '->' for sequential steps and ',' for concurrent ones. Every name must be the name of one of the agents. At most 2000 names in total: each name runs its agent once per loop, so a repeated name runs it again.

task
string | null

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

img
string | null

An optional https:// image URL or base64 encoded image that may be associated with the swarm's task or representation.

tasks
string[] | null

A list of tasks that the swarm should complete. The whole swarm runs once per task. At most 50.

Maximum array length: 50
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-5.4

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

heavy_swarm_worker_model_name
string | null
default:claude-sonnet-5

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

heavy_swarm_variant
enum<string> | null
default:default

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

Available options:
default,
medium,
heavy
council_judge_model_name
string | null
default:gpt-5.4

For CouncilAsAJudge: the model the evaluating judge agents use. The aggregator that writes the final ruling keeps its own default model, gpt-5.4.

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:false

For SequentialWorkflow and AgentRearrange: give every agent the framework's multi-agent collaboration prompt as a second system message. It tells each agent to restate its task in its own words, share its intermediate steps and ask another agent to verify its work. Off by default, as in SwarmRouter. Other swarm types ignore it.

heavy_swarm_max_loops
integer | null
default:1

For HeavySwarm: how many times the whole pipeline runs (question generation, the workers, then synthesis). It is not a per-agent loop limit.

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.

director_model_name
string | null
default:gpt-5.4

The model name to use for the director/overseer agent (if any). For HierarchicalSwarm, this is the model name of the director.

director_settings
DirectorSettings · object | null

Optional settings for the director agent. For HierarchicalSwarm, this configures the director. Accepts only agent_name, system_prompt, planning_system_prompt, temperature (0 to 2), top_p and max_tokens (1 to 128000). Any other key returns 422. temperature and top_p reach the director's model only when set here; otherwise the model's own default applies.

Response

Successful Response

job_id
string | null
required

The unique identifier for the swarm completion.

status
string | null
required

The status of the swarm completion.

swarm_name
string | null
required

The name of the swarm.

description
string | null
required

The description of the swarm.

swarm_type
string | null
required

The type of the swarm.

output
any | null
required

The output of the swarm.

number_of_agents
integer | null
required

The number of agents in the swarm.

execution_time
number | null
required

The execution time of the swarm.

usage
Usage · object | null
required

The usage of the swarm.

tasks
string[] | null

The batch of tasks the request carried, echoed back so a caller can match results to what it sent. null for a single-task run.

messages
object