Sign in
Swarms
Batch Processing

Execute Batch Swarm Completions

Execute multiple swarm completions concurrently using optimized thread pool execution. This is a premium-only feature.

post/v1/swarm/batch/completions

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

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

taskstring nullable

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

imgstring nullable

An optional image URL 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.

director_settingsobject nullable

Optional settings or hyperparameters for the director agent. For HierarchicalSwarm, this is the settings of the director. You can set temperature, top_p, max_tokens, etc.

Response

Successful Response

statusstring nullable

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

swarm_namestring nullable

The name of the swarm.

{"stackTrail":"components:schemas:SwarmBatchCompletionOutput:properties:result:anyOf","oasType":"schema","type":"unknown","title":"Result","description":"The result of the swarm execution (present on success).","nullable":true}
usageobject nullable

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

detailstring nullable

Error details for the swarm (present on error).

Changes

Changed in 11 of the 80 revisions of this API.8457

  • 1fec3d2320ed1See the full diff
    • ○

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

      request-property-default-value-changed

  • e05df8f412ad21See the full diff
    • ▲

      removed the enum value BatchedGridWorkflow of the request property //

      request-property-enum-value-removed

    • ▲

      removed the enum value auto of the request property //

      request-property-enum-value-removed

    • ○

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

      request-property-enum-value-added

  • 0882a16375db14See the full diff
    • ▲

      removed from the //// request property anyOf list

      request-property-any-of-removed

    • ○

      added the new optional request property ////

      new-optional-request-property

    • ○

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

      request-property-any-of-added

    • ○

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

      request-property-any-of-added

    • ○

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

      request-property-any-of-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • b7b92eb482fe1See the full diff
    • ▲

      the // request property's max was decreased to 50.00

      request-property-max-decreased

  • 35f4c5ec5bfd1See the full diff
    • ●

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

      request-property-max-set

  • dd6e1de072c711See the full diff
    • ●

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

      request-property-min-set

    • ○

      the request property default value medium was removed

      request-property-default-value-removed

  • 74ed1cde0bfc2See the full diff
    • ○

      added the new optional request property ////

      new-optional-request-property

    • ○

      added the new optional request property ////

      new-optional-request-property

  • dcbc7787aed73See the full diff
    • ○

      added the new optional request property ////

      new-optional-request-property

    • ○

      the request property default value changed from true to false

      request-property-default-value-changed

    • ○

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

      request-property-default-value-changed

  • 90f1182a9c4d126See the full diff
    • ▲

      removed the enum value AutoSwarmBuilder of the request property //

      request-property-enum-value-removed

    • ○

      added the new optional request property //////

      new-optional-request-property

    • ○

      added the new optional request property //////

      new-optional-request-property

    • ○

      added the new optional request property //////

      new-optional-request-property

    • ○

      added the new optional request property //////

      new-optional-request-property

    • ○

      added the new optional request property //////

      new-optional-request-property

    • ○

      added the new optional request property //////

      new-optional-request-property

    • ○

      added the new optional request property //////

      new-optional-request-property

    • ○

      added the new optional request property //////

      new-optional-request-property

    • ○

      added the new optional request property //////

      new-optional-request-property

    • ○

      added the new optional request property //////

      new-optional-request-property

    • ○

      added the new optional request property //////

      new-optional-request-property

    • ○

      added the new optional request property ////////

      new-optional-request-property

    • ○

      added the new optional request property ////////

      new-optional-request-property

    • ○

      added the new optional request property ////////

      new-optional-request-property

    • ○

      added the new optional request property ////////

      new-optional-request-property

    • ○

      added the new optional request property ////////

      new-optional-request-property

    • ○

      added the new optional request property ////////

      new-optional-request-property

    • ○

      added the new optional request property ////////

      new-optional-request-property

    • ○

      added the new optional request property ////////

      new-optional-request-property

    • ○

      added the new optional request property ////////

      new-optional-request-property

    • ○

      added the new optional request property ////////

      new-optional-request-property

    • ○

      added the new optional request property ////////

      new-optional-request-property

    • ○

      the request property default value changed from 10 to 30

      request-property-default-value-changed

    • ○

      the request property default value changed from 10 to 30

      request-property-default-value-changed

    • ○

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

      request-property-enum-value-added

    • ○

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

      request-property-enum-value-added

  • a4b2639c845e15See the full diff
    • ▲

      removed the enum value minimal of the request property /////

      request-property-enum-value-removed

    • ○

      the request property default value changed from 8192 to 16000

      request-property-default-value-changed

    • ○

      the request property default value changed from low to medium

      request-property-default-value-changed

    • ○

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

      request-property-enum-value-added

    • ○

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

      request-property-enum-value-added

    • ○

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

      request-property-enum-value-added