Skip to main content
POST
Execute Batch Swarm Completions

Headers

x-api-key
string
required

Body

application/json
Maximum array length: 50
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

status
string | null

The execution status of the swarm ('success' or 'error').

swarm_name
string | null

The name of the swarm.

result
any | null

The result of the swarm execution (present on success).

usage
Usage · object | null

Resource usage statistics for the swarm (present on success).

detail
string | null

Error details for the swarm (present on error).