Skip to main content
POST
/
v1
/
swarm
/
completions
{
  "job_id": "<string>",
  "status": "<string>",
  "swarm_name": "<string>",
  "description": "<string>",
  "swarm_type": "<string>",
  "output": "<any>",
  "number_of_agents": 123,
  "service_tier": "<string>",
  "execution_time": 123,
  "usage": {}
}

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 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,
HiearchicalSwarm,
auto,
MajorityVoting,
MALT,
DeepResearchSwarm,
CouncilAsAJudge,
InteractiveGroupChat,
HeavySwarm
​
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.

​
rules
string | null

Guidelines or constraints that govern the behavior and interactions of the agents within the swarm.

​
tasks
string[] | null

A list of tasks that the swarm should complete.

​
messages

A list of messages that the swarm should complete.

​
stream
boolean | null
default:false

A flag indicating whether the swarm should stream its output.

​
service_tier
string | null
default:standard

The service tier to use for processing. Options: 'standard' (default) or 'flex' for lower cost but slower processing.

​
heavy_swarm_loops_per_agent
integer | null
default:1

The number of loops to run per agent in the heavy swarm.

​
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.

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
required

The output of the swarm.

​
number_of_agents
integer | null
required

The number of agents in the swarm.

​
service_tier
string | null
required

The service tier of the swarm.

​
execution_time
number | null
required

The execution time of the swarm.

​
usage
object | null
required

The usage of the swarm.

⌘I