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

Swarm Type: HeavySwarm

Overview

The HeavySwarm is a sophisticated multi-agent orchestration system inspired by X.AI’s Grok 4 Heavy architecture. It automatically decomposes complex tasks into specialized questions and executes them using a built-in team of specialized agents — by default Research, Analysis, Alternatives, Verification, and Synthesis. Unlike other swarm types, HeavySwarm creates and manages its own agents internally — pass an empty agents array ("agents": []) in the request. The size and composition of that internal team is controlled by heavy_swarm_variant (see below). Key features:

Automatic Task Decomposition: Complex tasks are intelligently broken down into specialized questions using function calling
Specialized Agent Teams: In the default variant, Research, Analysis, Alternatives, Verification, and Synthesis agents work in concert
Parallel Execution: Specialist agents execute simultaneously for maximum efficiency
Iterative Refinement: Multi-loop execution where each loop builds upon previous results
Comprehensive Synthesis: A dedicated synthesis agent integrates all findings into an executive-ready report

Architecture

The HeavySwarm follows a structured 5-phase workflow:

Task Decomposition — A question generation agent analyzes the input task and creates four specialized questions using function calling
Parallel Execution — Four specialized agents (Research, Analysis, Alternatives, Verification) execute their questions simultaneously
Result Collection — Outputs are validated and collected from all agents
Synthesis — A fifth Synthesis agent integrates all results into a comprehensive report
Iterative Refinement — When heavy_swarm_max_loops > 1, the process repeats with context from previous iterations

Specialized Agents

Agent	Role
Research Agent	Comprehensive information gathering, source verification, data collection, and systematic search strategies
Analysis Agent	Statistical analysis, pattern recognition, causal relationship identification, and predictive modeling
Alternatives Agent	Strategic option generation, creative problem-solving, scenario planning, and trade-off analysis
Verification Agent	Fact-checking, feasibility assessment, risk assessment, and compliance verification
Synthesis Agent	Multi-perspective integration, executive summaries, strategic alignment, and actionable recommendations

HeavySwarm-Specific Parameters

Since HeavySwarm manages its own agents, it uses dedicated parameters at the swarm configuration level:

Parameter	Type	Default	Description
`heavy_swarm_max_loops`	`integer`	`1`	Number of execution loops per agent. Higher values enable iterative refinement for deeper analysis.
`heavy_swarm_question_agent_model_name`	`string`	`"gpt-5.4"`	Model used for the question generation phase. This agent decomposes the task into specialized questions.
`heavy_swarm_worker_model_name`	`string`	`"claude-sonnet-4-20250514"`	Model used for all five specialized worker agents (Research, Analysis, Alternatives, Verification, Synthesis).
`heavy_swarm_variant`	`string`	`"default"`	Which agent variant to run. One of `"default"`, `"medium"`, or `"heavy"`.

heavy_swarm_variant swaps the entire worker roster, not just a setting:

Variant	Worker count	Composition
`"default"`	5	The Research, Analysis, Alternatives, Verification, and Synthesis agents described above.
`"medium"`	4	A Captain-Swarm leader plus Harper (research/facts), Benjamin (logic/math/code), and Lucas (creative/contrarian analysis).
`"heavy"`	16	A Grok-style captain coordinating 15 domain specialists for maximum coverage.

heavy_swarm_worker_model_name applies to every worker in the chosen variant. The question-generation phase always uses heavy_swarm_question_agent_model_name, regardless of variant.

Use Cases

Deep research and comprehensive market analysis
Due diligence and investment research
Policy analysis and strategic planning
Technology assessment and competitive intelligence
Complex problem-solving requiring multiple perspectives
Medical or scientific research synthesis

API Usage

Basic HeavySwarm Example

Shell (curl)
Python (requests)
JavaScript (fetch)
Go
Rust

curl -X POST "https://api.swarms.world/v1/swarm/completions" \
  -H "x-api-key: $SWARMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Market Research Swarm",
    "description": "Comprehensive market analysis using HeavySwarm",
    "swarm_type": "HeavySwarm",
    "task": "Analyze the current state and future outlook of the renewable energy sector, including market trends, key players, investment opportunities, regulatory landscape, and technological innovations",
    "agents": [],
    "heavy_swarm_max_loops": 1,
    "heavy_swarm_question_agent_model_name": "gpt-5.4",
    "heavy_swarm_worker_model_name": "claude-sonnet-4-20250514",
    "max_loops": 1
  }'

import requests
import json

API_BASE_URL = "https://api.swarms.world"
API_KEY = "your_api_key_here"

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

swarm_config = {
    "name": "Market Research Swarm",
    "description": "Comprehensive market analysis using HeavySwarm",
    "swarm_type": "HeavySwarm",
    "task": "Analyze the current state and future outlook of the renewable energy sector, including market trends, key players, investment opportunities, regulatory landscape, and technological innovations",
    "agents": [],
    "heavy_swarm_max_loops": 1,
    "heavy_swarm_question_agent_model_name": "gpt-5.4",
    "heavy_swarm_worker_model_name": "claude-sonnet-4-20250514",
    "max_loops": 1
}

response = requests.post(
    f"{API_BASE_URL}/v1/swarm/completions",
    headers=headers,
    json=swarm_config
)

if response.status_code == 200:
    result = response.json()
    print(json.dumps(result["output"], indent=2))
else:
    print(f"Error: {response.status_code} - {response.text}")

const API_BASE_URL = "https://api.swarms.world";
const API_KEY = "your_api_key_here";

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

const swarmConfig = {
    name: "Market Research Swarm",
    description: "Comprehensive market analysis using HeavySwarm",
    swarm_type: "HeavySwarm",
    task: "Analyze the current state and future outlook of the renewable energy sector, including market trends, key players, investment opportunities, regulatory landscape, and technological innovations",
    agents: [],
    heavy_swarm_max_loops: 1,
    heavy_swarm_question_agent_model_name: "gpt-5.4",
    heavy_swarm_worker_model_name: "claude-sonnet-4-20250514",
    max_loops: 1
};

fetch(`${API_BASE_URL}/v1/swarm/completions`, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(swarmConfig)
})
.then(response => response.json())
.then(result => {
    if (result.status === "success") {
        console.log("HeavySwarm completed successfully!");
        console.log("Output:", JSON.stringify(result.output, null, 2));
    }
})
.catch(error => console.error("Error:", error));

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

type SwarmConfig struct {
    Name                          string        `json:"name"`
    Description                   string        `json:"description"`
    SwarmType                     string        `json:"swarm_type"`
    Task                          string        `json:"task"`
    Agents                        []interface{} `json:"agents"`
    HeavySwarmMaxLoops            int           `json:"heavy_swarm_max_loops"`
    HeavySwarmQuestionAgentModel  string        `json:"heavy_swarm_question_agent_model_name"`
    HeavySwarmWorkerModel         string        `json:"heavy_swarm_worker_model_name"`
    MaxLoops                      int           `json:"max_loops"`
}

func main() {
    API_BASE_URL := "https://api.swarms.world"
    API_KEY := "your_api_key_here"

    swarmConfig := SwarmConfig{
        Name:                          "Market Research Swarm",
        Description:                   "Comprehensive market analysis using HeavySwarm",
        SwarmType:                     "HeavySwarm",
        Task:                          "Analyze the current state and future outlook of the renewable energy sector, including market trends, key players, investment opportunities, regulatory landscape, and technological innovations",
        Agents:                        []interface{}{},
        HeavySwarmMaxLoops:            1,
        HeavySwarmQuestionAgentModel:  "gpt-5.4",
        HeavySwarmWorkerModel:         "claude-sonnet-4-20250514",
        MaxLoops:                      1,
    }

    jsonData, _ := json.Marshal(swarmConfig)

    req, _ := http.NewRequest("POST", API_BASE_URL+"/v1/swarm/completions", bytes.NewBuffer(jsonData))
    req.Header.Set("x-api-key", API_KEY)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Printf("Response: %s\n", string(body))
}

use reqwest::Client;
use serde_json::{json, Value};
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let api_base_url = "https://api.swarms.world";
    let api_key = "your_api_key_here";

    let swarm_config = json!({
        "name": "Market Research Swarm",
        "description": "Comprehensive market analysis using HeavySwarm",
        "swarm_type": "HeavySwarm",
        "task": "Analyze the current state and future outlook of the renewable energy sector, including market trends, key players, investment opportunities, regulatory landscape, and technological innovations",
        "agents": [],
        "heavy_swarm_max_loops": 1,
        "heavy_swarm_question_agent_model_name": "gpt-5.4",
        "heavy_swarm_worker_model_name": "claude-sonnet-4-20250514",
        "max_loops": 1
    });

    let client = Client::new();
    let response = client
        .post(&format!("{}/v1/swarm/completions", api_base_url))
        .header("x-api-key", api_key)
        .header("Content-Type", "application/json")
        .json(&swarm_config)
        .send()
        .await?;

    if response.status().is_success() {
        let result: Value = response.json().await?;
        println!("HeavySwarm completed successfully!");
        println!("Response: {:?}", result);
    } else {
        println!("Error: {}", response.status());
    }

    Ok(())
}

Multi-Loop Deep Analysis Example

Use multiple loops for iterative refinement where each loop builds upon the previous results:

Shell (curl)
Python (requests)
JavaScript (fetch)
Go
Rust

curl -X POST "https://api.swarms.world/v1/swarm/completions" \
  -H "x-api-key: $SWARMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deep Due Diligence Swarm",
    "description": "Multi-loop investment due diligence analysis",
    "swarm_type": "HeavySwarm",
    "task": "Conduct a comprehensive due diligence analysis on the AI semiconductor industry, evaluating NVIDIA, AMD, and Intel as investment opportunities. Assess financial health, competitive positioning, supply chain risks, and 5-year growth projections",
    "agents": [],
    "heavy_swarm_max_loops": 3,
    "heavy_swarm_question_agent_model_name": "gpt-5.4",
    "heavy_swarm_worker_model_name": "claude-sonnet-4-20250514",
    "max_loops": 2
  }'

import requests
import json

API_BASE_URL = "https://api.swarms.world"
API_KEY = "your_api_key_here"

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

swarm_config = {
    "name": "Deep Due Diligence Swarm",
    "description": "Multi-loop investment due diligence analysis",
    "swarm_type": "HeavySwarm",
    "task": "Conduct a comprehensive due diligence analysis on the AI semiconductor industry, evaluating NVIDIA, AMD, and Intel as investment opportunities. Assess financial health, competitive positioning, supply chain risks, and 5-year growth projections",
    "agents": [],
    "heavy_swarm_max_loops": 3,
    "heavy_swarm_question_agent_model_name": "gpt-5.4",
    "heavy_swarm_worker_model_name": "claude-sonnet-4-20250514",
    "max_loops": 2
}

response = requests.post(
    f"{API_BASE_URL}/v1/swarm/completions",
    headers=headers,
    json=swarm_config
)

if response.status_code == 200:
    result = response.json()
    print(json.dumps(result["output"], indent=2))
else:
    print(f"Error: {response.status_code} - {response.text}")

const API_BASE_URL = "https://api.swarms.world";
const API_KEY = "your_api_key_here";

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

const swarmConfig = {
    name: "Deep Due Diligence Swarm",
    description: "Multi-loop investment due diligence analysis",
    swarm_type: "HeavySwarm",
    task: "Conduct a comprehensive due diligence analysis on the AI semiconductor industry, evaluating NVIDIA, AMD, and Intel as investment opportunities. Assess financial health, competitive positioning, supply chain risks, and 5-year growth projections",
    agents: [],
    heavy_swarm_max_loops: 3,
    heavy_swarm_question_agent_model_name: "gpt-5.4",
    heavy_swarm_worker_model_name: "claude-sonnet-4-20250514",
    max_loops: 2
};

fetch(`${API_BASE_URL}/v1/swarm/completions`, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(swarmConfig)
})
.then(response => response.json())
.then(result => {
    if (result.status === "success") {
        console.log("Deep analysis completed!");
        console.log("Output:", JSON.stringify(result.output, null, 2));
    }
})
.catch(error => console.error("Error:", error));

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

type SwarmConfig struct {
    Name                          string        `json:"name"`
    Description                   string        `json:"description"`
    SwarmType                     string        `json:"swarm_type"`
    Task                          string        `json:"task"`
    Agents                        []interface{} `json:"agents"`
    HeavySwarmMaxLoops            int           `json:"heavy_swarm_max_loops"`
    HeavySwarmQuestionAgentModel  string        `json:"heavy_swarm_question_agent_model_name"`
    HeavySwarmWorkerModel         string        `json:"heavy_swarm_worker_model_name"`
    MaxLoops                      int           `json:"max_loops"`
}

func main() {
    API_BASE_URL := "https://api.swarms.world"
    API_KEY := "your_api_key_here"

    swarmConfig := SwarmConfig{
        Name:                          "Deep Due Diligence Swarm",
        Description:                   "Multi-loop investment due diligence analysis",
        SwarmType:                     "HeavySwarm",
        Task:                          "Conduct a comprehensive due diligence analysis on the AI semiconductor industry, evaluating NVIDIA, AMD, and Intel as investment opportunities. Assess financial health, competitive positioning, supply chain risks, and 5-year growth projections",
        Agents:                        []interface{}{},
        HeavySwarmMaxLoops:            3,
        HeavySwarmQuestionAgentModel:  "gpt-5.4",
        HeavySwarmWorkerModel:         "claude-sonnet-4-20250514",
        MaxLoops:                      2,
    }

    jsonData, _ := json.Marshal(swarmConfig)

    req, _ := http.NewRequest("POST", API_BASE_URL+"/v1/swarm/completions", bytes.NewBuffer(jsonData))
    req.Header.Set("x-api-key", API_KEY)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Printf("Response: %s\n", string(body))
}

use reqwest::Client;
use serde_json::{json, Value};
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let api_base_url = "https://api.swarms.world";
    let api_key = "your_api_key_here";

    let swarm_config = json!({
        "name": "Deep Due Diligence Swarm",
        "description": "Multi-loop investment due diligence analysis",
        "swarm_type": "HeavySwarm",
        "task": "Conduct a comprehensive due diligence analysis on the AI semiconductor industry, evaluating NVIDIA, AMD, and Intel as investment opportunities. Assess financial health, competitive positioning, supply chain risks, and 5-year growth projections",
        "agents": [],
        "heavy_swarm_max_loops": 3,
        "heavy_swarm_question_agent_model_name": "gpt-5.4",
        "heavy_swarm_worker_model_name": "claude-sonnet-4-20250514",
        "max_loops": 2
    });

    let client = Client::new();
    let response = client
        .post(&format!("{}/v1/swarm/completions", api_base_url))
        .header("x-api-key", api_key)
        .header("Content-Type", "application/json")
        .json(&swarm_config)
        .send()
        .await?;

    if response.status().is_success() {
        let result: Value = response.json().await?;
        println!("Deep analysis completed!");
        println!("Response: {:?}", result);
    } else {
        println!("Error: {}", response.status());
    }

    Ok(())
}

Example Response:

{
    "job_id": "swarms-K29xMFDrsmLHxCRoeyF3NVYvPaXk",
    "status": "success",
    "swarm_name": "Market Research Swarm",
    "description": "Comprehensive market analysis using HeavySwarm",
    "swarm_type": "HeavySwarm",
    "output": [
        {
            "role": "Question Generator Agent",
            "content": {
                "research_question": "What are the current global market size, growth rates, and key players across solar, wind, hydrogen, and battery storage segments?",
                "analysis_question": "What statistical patterns emerge from renewable energy adoption rates, cost curves, and capacity factor improvements over the past decade?",
                "alternatives_question": "What are the most promising investment strategies across renewable energy subsectors considering risk-adjusted returns and portfolio diversification?",
                "verification_question": "How do projected renewable energy cost trajectories and policy commitments align with independently verified deployment data and grid integration feasibility?"
            }
        },
        {
            "role": "Research-Agent",
            "content": "Comprehensive research findings on the renewable energy sector including market sizing data, key players analysis, regulatory landscape across major markets, and technological innovation timelines..."
        },
        {
            "role": "Analysis-Agent",
            "content": "Statistical analysis of renewable energy adoption patterns showing compound growth rates, learning curve analysis for solar PV and wind technologies, correlation between policy incentives and deployment rates..."
        },
        {
            "role": "Alternatives-Agent",
            "content": "Strategic investment alternatives analysis covering direct equity positions, ETF-based approaches, project finance opportunities, and emerging technology bets with detailed risk-return profiles..."
        },
        {
            "role": "Verification-Agent",
            "content": "Verification assessment of key claims including cross-referenced deployment data, validated cost projections against IRENA and BloombergNEF databases, feasibility assessment of grid integration targets..."
        },
        {
            "role": "Synthesis-Agent",
            "content": "Executive Summary: The renewable energy sector presents strong investment fundamentals with verified compound growth trajectories. Key Insights: Solar PV costs have declined 89% since 2010, wind energy capacity factors have improved 25%... Actionable Recommendations: 1. Overweight solar and battery storage... Risks & Mitigation: Supply chain concentration in key materials..."
        }
    ],
    "number_of_agents": 0,
    "execution_time": 62.4,
    "usage": {
        "input_tokens": 85,
        "output_tokens": 5400,
        "total_tokens": 5485,
        "billing_info": {
            "cost_breakdown": {
                "agent_cost": 0.0,
                "input_token_cost": 0.000553,
                "output_token_cost": 0.0999,
                "token_counts": {
                    "total_input_tokens": 85,
                    "total_output_tokens": 5400,
                    "total_tokens": 5485
                },
                "num_agents": 0,
                "night_time_discount_applied": false
            },
            "total_cost": 0.100453,
            "discount_active": false,
            "discount_type": "none",
            "discount_percentage": 0
        }
    }
}

Because the request’s agents array stays empty, number_of_agents in the response — and the flat per-agent billing fee that scales with it — is 0 for HeavySwarm, regardless of how many workers the chosen heavy_swarm_variant actually runs internally. You are still billed for the input and output tokens all of those internal agents consume.

Best Practices

Use HeavySwarm for complex tasks that benefit from multi-perspective analysis rather than simple queries
Start with heavy_swarm_max_loops: 1 and increase only when deeper iterative analysis is needed
Choose the question agent model carefully — it determines the quality of task decomposition which drives the entire workflow
Use a capable worker model (e.g., claude-sonnet-4-20250514) for the specialized agents to get high-quality research, analysis, and verification
HeavySwarm requires an empty agents array ("agents": []) in the request — the worker team is created and managed internally, sized by heavy_swarm_variant
For time-sensitive tasks, keep max_loops at 1; increase for comprehensive research where thoroughness is prioritized over speed
Schedule non-urgent deep analysis during off-peak hours (8 PM - 6 AM PT) for cost savings

Getting Started

Clients

Agent Completions

Multi-Agent

Batch

Capabilities

Resources

Swarms Cloud

HeavySwarm

Overview

Architecture

Specialized Agents

HeavySwarm-Specific Parameters

Use Cases

API Usage

Basic HeavySwarm Example

Multi-Loop Deep Analysis Example

Best Practices

​Overview

​Architecture

​Specialized Agents

​HeavySwarm-Specific Parameters

​Use Cases

​API Usage

​Basic HeavySwarm Example

​Multi-Loop Deep Analysis Example

​Best Practices

Overview

Architecture

Specialized Agents

HeavySwarm-Specific Parameters

Use Cases

API Usage

Basic HeavySwarm Example

Multi-Loop Deep Analysis Example

Best Practices