THthe-swarm-corporation
Swarms

Execute Swarm Completion

Changed on

Execute a swarm completion with the specified task. Supports both standard and streaming responses.

post/v1/swarm/completions

Request

  • Base URL
    https://api.swarms.world
  • URL
    https://api.swarms.world/v1/swarm/completions
  • Auth
    none declared. Required headers: x-api-key

Headers

x-api-keystring required

Request body

namestring nullable

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

descriptionstring nullable

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

max_loopsinteger nullable

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

swarm_type'AgentRearrange' | 'MixtureOfAgents' | 'SequentialWorkflow' | 'ConcurrentWorkflow' | 'GroupChat' | 'MultiAgentRouter' | 'HierarchicalSwarm' | 'MajorityVoting' | 'CouncilAsAJudge' | 'HeavySwarm' | 'LLMCouncil' | 'DebateWithJudge' | 'RoundRobin' | 'PlannerWorkerSwarm' nullable

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

rearrange_flowstring nullable

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.

taskstring nullable

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

imgstring nullable

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

tasksstring[] nullable

A list of tasks that the swarm should complete.

streamboolean nullable

A flag indicating whether the swarm should stream its output.

heavy_swarm_question_agent_model_namestring nullable

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

heavy_swarm_worker_model_namestring nullable

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

heavy_swarm_variant'default' | 'medium' | 'heavy' nullable

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

council_judge_model_namestring nullable

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

chairman_modelstring nullable

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

multi_agent_collab_promptboolean nullable

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

heavy_swarm_max_loopsinteger nullable

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

list_all_agentsboolean nullable

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

director_model_namestring nullable

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

Response

Successful Response

job_idstring nullable required

The unique identifier for the swarm completion.

statusstring nullable required

The status of the swarm completion.

swarm_namestring nullable required

The name of the swarm.

descriptionstring nullable required

The description of the swarm.

swarm_typestring nullable required

The type of the swarm.

outputunknown required
number_of_agentsinteger nullable required

The number of agents in the swarm.

execution_timenumber nullable required

The execution time of the swarm.

usageobject nullable required

The usage of the swarm.

tasksstring[] nullable

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

Changes

  • fca99f497199Revision changes
    • breaking

      removed subschema #1 from the request property anyOf list

    • info

      added to the request property anyOf list

  • 500c79520e41Revision changes
    • breaking

      removed from the /// request property anyOf list

    • breaking

      request property //// was restricted to a list of enum values

    • breaking

      removed the enum value AutoSwarmBuilder of the request property /

    • breaking

      removed the enum value DeepResearchSwarm of the request property /

    • breaking

      removed the enum value HiearchicalSwarm of the request property /

    • breaking

      removed the enum value InteractiveGroupChat of the request property /

    • breaking

      removed the enum value MALT of the request property /

    • breaking

      removed the enum value auto of the request property /

    • breaking

      removed the required property from the response with the status

    • warning

      the //// request property's max was set to 2.00

    • warning

      the / request property's max was set to 50.00

    • warning

      the //// request property's min was set to 1.00

    • warning

      the //// request property's min was set to 0.00

    • warning

      removed the request property

    • warning

      removed the request property

    • warning

      removed the request property

    • info

      api tag Swarms added

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property /////

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property ///

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added subschema #3 to the /// request property anyOf list

    • info

      added subschema #1 to the /// request property anyOf list

    • info

      added subschema #2 to the /// request property anyOf list

    • info

      the request property /// became optional

    • info

      the request property default value changed from true to false

    • info

      the request property default value changed from gpt-4.1 to gpt-5.4

    • info

      the request property default value changed from 8192 to 16000

    • info

      the request property default value changed from gpt-4.1 to claude-sonnet-5

    • info

      the request property default value changed from 10 to 30

    • info

      the request property default value changed from streamable_http to auto

    • info

      the request property default value 0.5 was removed

    • info

      added the new DebateWithJudge enum value to the request property /

    • info

      added the new HierarchicalSwarm enum value to the request property /

    • info

      added the new LLMCouncil enum value to the request property /

    • info

      added the new None enum value to the request property ////

    • info

      added the new PlannerWorkerSwarm enum value to the request property /

    • info

      added the new RoundRobin enum value to the request property /

    • info

      added the new high enum value to the request property ////

    • info

      added the new low enum value to the request property ////

    • info

      added the new max enum value to the request property ////

    • info

      added the new medium enum value to the request property ////

    • info

      added the new minimal enum value to the request property ////

    • info

      added the new none enum value to the request property ////

    • info

      added the new ultra enum value to the request property ////

    • info

      added the new xhigh enum value to the request property ////

    • info

      request property /// list-of-types was widened by adding types string to media type application/json

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status