Swarms API Documentation - Build AI Agents & Multi-Agent Systems

Premium Tier Required: The /v1/swarm/batch/completions endpoint is restricted to Pro, Ultra, and Premium plan subscribers. Free tier users will receive a 403 error. See Premium Endpoints.

Multi-Agent vs Single Agent: This example covers batch processing for multi-agent swarms (/v1/swarm/batch/completions). For batching single agent tasks, see Batch Agent Completions (Single Agent).

Run many swarm jobs in a single API call using /v1/swarm/batch/completions.
This is ideal for:

Evaluating the same swarm configuration across many tasks
Running different swarm types side‑by‑side
Large‑scale research, content generation, or analysis workloads

All requests share the same base URL:

https://api.swarms.world

Quick Start: Batch Swarm Completion

Each item in the batch is a full SwarmSpec (the same structure used for /v1/swarm/completions).

Python
TypeScript
Rust

import os
import json
import requests
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"

headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json",
}

# Define a couple of swarms to run in parallel
batch_payload = [
    {
        "name": "Market Analysis Swarm",
        "description": "Sequential research swarm for market analysis",
        "swarm_type": "SequentialWorkflow",
        "task": "Analyze 2025 AI agent market trends and key players.",
        "max_loops": 1,
        "agents": [
            {
                "agent_name": "Research-Analyst",
                "description": "Collects and summarizes market information.",
                "system_prompt": "You are a senior market research analyst.",
                "model_name": "gpt-4.1",
                "max_tokens": 1500,
                "temperature": 0.4,
            }
        ],
    },
    {
        "name": "Technical Review Swarm",
        "description": "Concurrent workflow for technical deep‑dives",
        "swarm_type": "ConcurrentWorkflow",
        "task": "Compare Rust and TypeScript for backend microservices.",
        "max_loops": 1,
        "agents": [
            {
                "agent_name": "Rust-Expert",
                "description": "Analyzes Rust for backend services.",
                "system_prompt": "You are a senior Rust engineer.",
                "model_name": "gpt-4.1",
                "max_tokens": 1000,
            },
            {
                "agent_name": "TypeScript-Expert",
                "description": "Analyzes TypeScript/Node.js for backend services.",
                "system_prompt": "You are a senior TypeScript backend engineer.",
                "model_name": "gpt-4.1",
                "max_tokens": 1000,
            },
        ],
    },
]


def run_batch_swarm_completions():
    response = requests.post(
        f"{BASE_URL}/v1/swarm/batch/completions",
        headers=headers,
        json=batch_payload,
        timeout=600,
    )

    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    results = run_batch_swarm_completions()
    print("✅ Batch swarm completions finished")
    print(json.dumps(results, indent=2))

import 'dotenv/config'

const API_KEY = process.env.SWARMS_API_KEY
const BASE_URL = 'https://api.swarms.world'

if (!API_KEY) {
  throw new Error('SWARMS_API_KEY is not set')
}

type AgentSpec = {
  agent_name?: string
  description?: string
  system_prompt?: string
  model_name?: string
  max_tokens?: number
  temperature?: number
  max_loops?: number | string
}

type SwarmSpec = {
  name?: string
  description?: string
  swarm_type?: string
  task?: string
  max_loops?: number
  agents?: AgentSpec[]
}

async function runBatchSwarmCompletions(): Promise<unknown> {
  const batchPayload: SwarmSpec[] = [
    {
      name: 'Market Analysis Swarm',
      description: 'Sequential research swarm for market analysis',
      swarm_type: 'SequentialWorkflow',
      task: 'Analyze 2025 AI agent market trends and key players.',
      max_loops: 1,
      agents: [
        {
          agent_name: 'Research-Analyst',
          description: 'Collects and summarizes market information.',
          system_prompt: 'You are a senior market research analyst.',
          model_name: 'gpt-4.1',
          max_tokens: 1500,
          temperature: 0.4,
        },
      ],
    },
    {
      name: 'Technical Review Swarm',
      description: 'Concurrent workflow for technical deep‑dives',
      swarm_type: 'ConcurrentWorkflow',
      task: 'Compare Rust and TypeScript for backend microservices.',
      max_loops: 1,
      agents: [
        {
          agent_name: 'Rust-Expert',
          description: 'Analyzes Rust for backend services.',
          system_prompt: 'You are a senior Rust engineer.',
          model_name: 'gpt-4.1',
          max_tokens: 1000,
        },
        {
          agent_name: 'TypeScript-Expert',
          description: 'Analyzes TypeScript/Node.js for backend services.',
          system_prompt: 'You are a senior TypeScript backend engineer.',
          model_name: 'gpt-4.1',
          max_tokens: 1000,
        },
      ],
    },
  ]

  const res = await fetch(`${BASE_URL}/v1/swarm/batch/completions`, {
    method: 'POST',
    headers: {
      'x-api-key': API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(batchPayload),
  })

  if (!res.ok) {
    const text = await res.text()
    throw new Error(`HTTP ${res.status}: ${text}`)
  }

  return (await res.json()) as unknown
}

void runBatchSwarmCompletions()
  .then((results) => {
    console.log('✅ Batch swarm completions finished')
    console.log(JSON.stringify(results, null, 2))
  })
  .catch(console.error)

use std::env;

use reqwest::blocking::Client;
use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_key =
        env::var("SWARMS_API_KEY").expect("SWARMS_API_KEY environment variable is required");

    let client = Client::new();

    let batch_payload = json!([
        {
            "name": "Market Analysis Swarm",
            "description": "Sequential research swarm for market analysis",
            "swarm_type": "SequentialWorkflow",
            "task": "Analyze 2025 AI agent market trends and key players.",
            "max_loops": 1,
            "agents": [
                {
                    "agent_name": "Research-Analyst",
                    "description": "Collects and summarizes market information.",
                    "system_prompt": "You are a senior market research analyst.",
                    "model_name": "gpt-4.1",
                    "max_tokens": 1500,
                    "temperature": 0.4
                }
            ]
        },
        {
            "name": "Technical Review Swarm",
            "description": "Concurrent workflow for technical deep-dives",
            "swarm_type": "ConcurrentWorkflow",
            "task": "Compare Rust and TypeScript for backend microservices.",
            "max_loops": 1,
            "agents": [
                {
                    "agent_name": "Rust-Expert",
                    "description": "Analyzes Rust for backend services.",
                    "system_prompt": "You are a senior Rust engineer.",
                    "model_name": "gpt-4.1",
                    "max_tokens": 1000
                },
                {
                    "agent_name": "TypeScript-Expert",
                    "description": "Analyzes TypeScript/Node.js for backend services.",
                    "system_prompt": "You are a senior TypeScript backend engineer.",
                    "model_name": "gpt-4.1",
                    "max_tokens": 1000
                }
            ]
        }
    ]);

    let res = client
        .post("https://api.swarms.world/v1/swarm/batch/completions")
        .header("x-api-key", api_key)
        .header("Content-Type", "application/json")
        .json(&batch_payload)
        .send()?;

    res.error_for_status_ref()?;

    let body = res.text()?;
    println!("{body}");

    Ok(())
}

Interpreting the Response

The endpoint returns an array of results, one per item in the batch, in the same order as the request. Each entry is leaner than the single-swarm /v1/swarm/completions response — there is no job_id, swarm_type, or execution_time field, and the swarm’s output is under result, not output:

[
  {
    "status": "success",
    "swarm_name": "Market Analysis Swarm",
    "result": { "summary": "..." },
    "usage": {
      "input_tokens": 8500,
      "output_tokens": 3200,
      "total_tokens": 11700,
      "billing_info": {
        "cost_breakdown": {
          "agent_cost": 0.01,
          "input_token_cost": 0.055,
          "output_token_cost": 0.0592,
          "token_counts": {
            "total_input_tokens": 8500,
            "total_output_tokens": 3200,
            "total_tokens": 11700
          },
          "num_agents": 1,
          "night_time_discount_applied": false
        },
        "total_cost": 0.1242,
        "discount_active": false,
        "discount_type": "none",
        "discount_percentage": 0
      }
    }
  }
]

If a swarm in the batch fails, its entry has "status": "error" and a detail message instead of result/usage:

{
  "status": "error",
  "swarm_name": "Technical Review Swarm",
  "detail": "Failed to run swarm: ..."
}

Use swarm_name, status, and usage.billing_info.total_cost for auditing, cost tracking, and monitoring across your batch workloads. Check each entry’s status before reading result — a failed swarm does not raise an HTTP error for the whole batch, it just reports "status": "error" in its own slot.

Getting Started

Clients

Agent Completions

Multi-Agent

Batch

Capabilities

Resources

Swarms Cloud

Batch Swarm Completions (Multi-Agent)

Quick Start: Batch Swarm Completion

Interpreting the Response

​Quick Start: Batch Swarm Completion

​Interpreting the Response

Quick Start: Batch Swarm Completion

Interpreting the Response