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

Premium Tier Required: The /v1/agent/batch/completions endpoint is restricted to Pro, Ultra, and Premium plan subscribers. Free tier users will receive a 403 error. Upgrade your account to access batch processing capabilities.

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

Batch size limit: A single request to /v1/agent/batch/completions accepts at most 10 AgentCompletion items. Requests with more than 10 items are rejected with an HTTP 400 error. To process larger volumes, split your work into chunks of 10 and submit multiple requests — see Batch Agent Completions at Scale for a chunking pattern.

What This Example Shows

Processing multiple agent tasks in a single request
Configuring different agents for different types of analysis
Efficient batch execution for multiple related tasks
Handling diverse task types with specialized agents

Quick Start

Python
TypeScript
Rust
cURL

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 multiple batch requests (array of AgentCompletion)
batch_requests = [
    {
        "agent_config": {
            "agent_name": "Bloodwork Diagnosis Expert",
            "description": "Expert in blood work interpretation.",
            "system_prompt": (
                "You are a doctor who interprets blood work. Give concise, clear explanations and possible diagnoses."
            ),
            "model_name": "gpt-4.1",
            "max_loops": 1,
            "max_tokens": 1000,
            "temperature": 0.5,
        },
        "task": (
            "Blood work: Hemoglobin 10.2 (low), WBC 13,000 (high), Platelets 180,000 (normal), "
            "ALT 65 (high), AST 70 (high). Interpret and suggest diagnoses."
        ),
    },
    {
        "agent_config": {
            "agent_name": "Radiology Report Summarizer",
            "description": "Expert in summarizing radiology reports.",
            "system_prompt": (
                "You are a radiologist. Summarize the findings of radiology reports in clear, patient-friendly language."
            ),
            "model_name": "gpt-4.1",
            "max_loops": 1,
            "max_tokens": 1000,
            "temperature": 0.5,
        },
        "task": (
            "Radiology report: Chest X-ray shows mild cardiomegaly, no infiltrates, no effusion. Summarize the findings."
        ),
    },
]


def run_agent_batch_completions():
    response = requests.post(
        f"{BASE_URL}/v1/agent/batch/completions",
        headers=headers,
        json=batch_requests,
        timeout=600,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = run_agent_batch_completions()
    print(json.dumps(result, indent=4))

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_loops?: number | string
  max_tokens?: number
  temperature?: number
}

type AgentCompletion = {
  agent_config: AgentSpec
  task?: string
}

async function runAgentBatchCompletions(): Promise<unknown> {
  const batchPayload: AgentCompletion[] = [
    {
      agent_config: {
        agent_name: 'Bloodwork Diagnosis Expert',
        description: 'Expert in blood work interpretation.',
        system_prompt:
          'You are a doctor who interprets blood work. Give concise, clear explanations and possible diagnoses.',
        model_name: 'gpt-4.1',
        max_loops: 1,
        max_tokens: 1000,
        temperature: 0.5,
      },
      task:
        'Blood work: Hemoglobin 10.2 (low), WBC 13,000 (high), Platelets 180,000 (normal), ALT 65 (high), AST 70 (high). Interpret and suggest diagnoses.',
    },
    {
      agent_config: {
        agent_name: 'Radiology Report Summarizer',
        description: 'Expert in summarizing radiology reports.',
        system_prompt:
          'You are a radiologist. Summarize the findings of radiology reports in clear, patient-friendly language.',
        model_name: 'gpt-4.1',
        max_loops: 1,
        max_tokens: 1000,
        temperature: 0.5,
      },
      task:
        'Radiology report: Chest X-ray shows mild cardiomegaly, no infiltrates, no effusion. Summarize the findings.',
    },
  ]

  const res = await fetch(`${BASE_URL}/v1/agent/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 runAgentBatchCompletions()
  .then((result) => {
    console.log('Batch Results:', JSON.stringify(result, 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!([
        {
            "agent_config": {
                "agent_name": "Bloodwork Diagnosis Expert",
                "description": "Expert in blood work interpretation.",
                "system_prompt": "You are a doctor who interprets blood work. Give concise, clear explanations and possible diagnoses.",
                "model_name": "gpt-4.1",
                "max_loops": 1,
                "max_tokens": 1000,
                "temperature": 0.5
            },
            "task": "Blood work: Hemoglobin 10.2 (low), WBC 13,000 (high), Platelets 180,000 (normal), ALT 65 (high), AST 70 (high). Interpret and suggest diagnoses."
        },
        {
            "agent_config": {
                "agent_name": "Radiology Report Summarizer",
                "description": "Expert in summarizing radiology reports.",
                "system_prompt": "You are a radiologist. Summarize the findings of radiology reports in clear, patient-friendly language.",
                "model_name": "gpt-4.1",
                "max_loops": 1,
                "max_tokens": 1000,
                "temperature": 0.5
            },
            "task": "Radiology report: Chest X-ray shows mild cardiomegaly, no infiltrates, no effusion. Summarize the findings."
        }
    ]);

    let res = client
        .post("https://api.swarms.world/v1/agent/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(())
}

curl -X POST "https://api.swarms.world/v1/agent/batch/completions" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "agent_config": {
        "agent_name": "Bloodwork Diagnosis Expert",
        "model_name": "gpt-4.1",
        "max_tokens": 1000,
        "temperature": 0.5
      },
      "task": "Blood work analysis..."
    },
    {
      "agent_config": {
        "agent_name": "Radiology Report Summarizer",
        "model_name": "gpt-4.1",
        "max_tokens": 1000,
        "temperature": 0.5
      },
      "task": "Radiology report summary..."
    }
  ]'

Batch Processing Benefits

Efficiency: Process multiple tasks in parallel
Cost Optimization: Reduce API call overhead
Consistency: Apply similar processing across multiple items
Scalability: Handle large volumes of work efficiently

Use Cases

Batch processing is ideal for:

Document Analysis: Review multiple contracts, reports, or documents
Data Processing: Analyze large datasets with multiple perspectives
Content Generation: Create variations of content for different audiences
Quality Assurance: Review multiple code files, designs, or content pieces
Customer Support: Process multiple support tickets with specialized agents

Expected Output

The batch processor will return results for each task:

Bloodwork analysis with diagnosis and recommendations
Radiology report summary in patient-friendly language
Each result maintains the structure and quality of individual agent runs

Environment Setup

Create a .env file in your project directory:

SWARMS_API_KEY=your_api_key_here

Advanced Batch Processing

You can extend this pattern to:

Dynamic Batching: Group similar tasks automatically
Priority Processing: Assign importance levels to different tasks
Result Aggregation: Combine multiple results into unified insights
Error Handling: Gracefully handle failures in individual batch items

Next Steps

After mastering batch processing, explore:

Multi-agent swarms for complex collaborative workflows
Sequential workflows for dependent tasks
Concurrent workflows for parallel execution
Agent routing for intelligent task distribution

Getting Started

Clients

Agent Completions

Multi-Agent

Batch

Capabilities

Resources

Swarms Cloud

Batch Agent Completions (Single Agent)

What This Example Shows

Quick Start

Batch Processing Benefits

Use Cases

Expected Output

Environment Setup

Advanced Batch Processing

Next Steps

​What This Example Shows

​Quick Start

​Batch Processing Benefits

​Use Cases

​Expected Output

​Environment Setup

​Advanced Batch Processing

​Next Steps

What This Example Shows

Quick Start

Batch Processing Benefits

Use Cases

Expected Output

Environment Setup

Advanced Batch Processing

Next Steps