Skip to main content
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).
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))

Interpreting the Response

The endpoint returns an array of swarm completion results, one per item in the batch:
[
  {
    "job_id": "batch-job-1",
    "status": "completed",
    "swarm_name": "Market Analysis Swarm",
    "description": "Sequential research swarm for market analysis",
    "swarm_type": "SequentialWorkflow",
    "output": { "summary": "..." },
    "number_of_agents": 1,
    "execution_time": 12.3,
    "usage": {
      "input_tokens": 8500,
      "output_tokens": 3200,
      "total_tokens": 11700,
      "token_cost": 0.0123
    }
  }
]
Use the job_id and usage fields for auditing, cost tracking, and monitoring across your batch workloads.