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

What is the Swarms API?

The Swarms API is a comprehensive platform for building and orchestrating AI agents and multi-agent systems. It enables developers to create individual intelligent agents or coordinate thousands of agents in complex workflows, allowing them to communicate, collaborate, and solve problems together.Key Benefits:

Agent Orchestration: Create and manage AI agents that can work independently or collaborate
Multi-Agent Communication: Enable agents to communicate and share information seamlessly
Flexible Workflows: Support for sequential, concurrent, hierarchical, and other workflow patterns
Enterprise Scale: A single swarm supports up to 2,000 agents (SwarmSpec.agents)
Multi-Model Support: Integration with OpenAI, Anthropic, and Groq models

Why should I use the Swarms API?

The Swarms API is designed for developers who need more than just a simple AI completion endpoint. Here’s why you should choose Swarms:

Complete Agent Ecosystem: Full ecosystem for building, deploying, and scaling intelligent AI systems
Advanced Multi-Agent Architectures: Build complex hierarchical, sequential, and parallel agent collaboration systems
Agent-to-Agent Communication: Advanced communication protocols enable seamless agent interaction
Ultra-Optimized Runtime: High-performance runtime with built-in optimization for concurrent operations
Enterprise-Ready: Built-in security, governance, and compliance features

How does agent orchestration work?

Agent orchestration in the Swarms API allows you to:

Create Individual Agents: Deploy single agents for specific tasks
Coordinate Multiple Agents: Build swarms where agents work together
Define Workflow Patterns: Choose from sequential, concurrent, hierarchical, and other patterns
Enable Communication: Agents can share information and collaborate
Scale Dynamically: Add or remove agents based on workload

Example Use Cases:

Research teams with multiple agents researching different aspects
Medical analysis with lab analyzer and clinical specialist working together
Financial analysis with market analyst and economic forecaster collaborating
Content creation with writer, editor, and fact-checker in sequence

What types of workflows are supported?

The swarm_type field on POST /v1/swarm/completions accepts 14 architectures:

Swarm Type	Description
SequentialWorkflow	Agents work in order, each building on the previous output
ConcurrentWorkflow	Agents work simultaneously on the same task
HierarchicalSwarm	A director agent delegates to worker agents
MultiAgentRouter	Intelligent task distribution based on agent capabilities
MixtureOfAgents	Diverse specialist agents combined for a single task
MajorityVoting	Consensus-based decision making across agents
AgentRearrange	Dynamic agent reconfiguration via a flow expression
GroupChat	Agents converse with one another to reach an outcome
CouncilAsAJudge	A panel of agents is evaluated by a judge model
HeavySwarm	Question, worker, and synthesis agents collaborate for deep analysis
LLMCouncil	A council of models is synthesized by a chairman model
DebateWithJudge	Two agents debate; a judge delivers a verdict
RoundRobin	Agents take turns in a fixed rotation
PlannerWorkerSwarm	A planner agent decomposes the task for worker agents

For each type’s full description, category, and tuning parameters, call GET /v1/swarms/available.

What models are supported?

The Swarms API accepts model ids from multiple providers (OpenAI, Anthropic, Google, xAI, Groq, and others) via the model_name field on AgentSpec. If model_name is omitted, the agent uses the default model, claude-sonnet-5.Premium-only models (rejected on the free tier, with a suggested free-tier alternative in the error response):

gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.6
claude-fable-5, claude-opus-5, claude-opus-4-8
gemini-3.1-pro, gemini-3.1-deep-think
xai/grok-4.5, xai/grok-4.5-latest
Any model id beginning with groq/

Free-tier alternatives the API suggests in place of these: claude-sonnet-5, gpt-5.5, gemini-3.5-flash (and claude-haiku-4-5, gpt-5.4-mini, gemini-3.5-flash-lite for the luna tier). Every other model id, including gpt-4.1, is available on the free tier.For the complete, up-to-date list of supported models, call GET /v1/models (or GET /v1/models/available for model metadata).

How much does it cost?

The Swarms API uses a transparent, usage-based pricing model with unified pricing across all endpoints:Unified Token Pricing:

Input Tokens: $6.50 per 1 million tokens (all endpoints)
Output Tokens: $18.50 per 1 million tokens (all endpoints)

Item	Cost	Notes
Base cost per agent	$0.01 per agent	Charged for each agent in swarms and workflows
Input tokens	$6.50 per 1M tokens	Unified pricing for all endpoints
Output tokens	$18.50 per 1M tokens	Unified pricing for all endpoints
MCP cost	$0.10 per call	Charged if an agent uses an MCP URL
Image cost	$0.25 per image	Charged for each image processed
Exa Search tool	$0.04 per search	Charged per search execution
Web Scraper tool	$0.15 per scrape	Charged per scrape execution
Night-time discount	50% off token costs	8 PM - 6 AM PT (Swarm Completions only)

Pricing applies to:

Swarm Completions (with agent cost)
Agent Completions
Graph Workflow (with agent cost)
Batched Grid Workflow (with agent cost)

Special Features:

Night Time Discount: 50% off token costs for Swarm Completions during 8 PM - 6 AM Pacific Time

For detailed pricing information, examples, and cost calculation formulas, see the Pricing page.

What are the rate limits?

Rate limits are tier-based to ensure fair usage:

Rate Limit Type	Free Tier	Premium Tier	Time Window
Requests per Minute	100	2,000	1 minute
Requests per Hour	350	10,000	1 hour
Requests per Day	1,200	100,000	24 hours
Tokens per Agent	200,000	2,000,000	Per request
Prompt Length	200,000	2,000,000	Per request
Batch Size	50	50	Per request

The batch size limit of 50 applies to all tiers.Premium Tier Benefits:

20x more requests per minute (2,000 vs 100)
28x more requests per hour (10,000 vs 350)
83x more requests per day (100,000 vs 1,200)
10x more tokens per agent (2M vs 200K)

Which endpoints require a Premium subscription?

Exactly five endpoints require a Pro, Ultra, or Premium subscription:

Endpoint	Feature
`POST /v1/agent/batch/completions`	Batch Agent Completions
`POST /v1/swarm/batch/completions`	Batch Swarm Completions
`POST /v1/reasoning-agent/completions`	Reasoning Agent Completions
`POST /v1/batched-grid-workflow/completions`	Batched Grid Workflows
`POST /v1/graph-workflow/completions`	Graph Workflows

Call GET /v1/account/premium-endpoints to fetch this list live, along with an upgrade link. All billable endpoints (including the free-tier ones above plus /v1/swarm/completions, /v1/chat/completions, and /v1/agent/completions) additionally require a total credit balance greater than $1.00.

How do I get started?

1. Get Your API Key Visit Swarms Platform to get your free API key.2. Install Client Libraries

# Python
pip install swarms-client

# JavaScript/TypeScript
npm install axios dotenv

3. Make Your First API Call

import os
from swarms_client import SwarmsClient
from dotenv import load_dotenv

load_dotenv()

client = SwarmsClient(
    api_key=os.getenv("SWARMS_API_KEY"),
)

result = client.agent.run(
    agent_config={
        "agent_name": "My First Agent",
        "system_prompt": "You are a helpful assistant.",
        "model_name": "gpt-4.1-mini",
        "max_tokens": 1000,
        "temperature": 0.7,
    },
    task="Hello, world!"
)

print(result)

What tools and integrations are available?

Built-in Tools:

Search Capabilities: Web search integration for research tasks
MCP Integration: Model Context Protocol for enhanced interactions
Custom Tools: Define your own function tools for specific needs

MCP (Model Context Protocol) Integration:

Connect to external data sources
Integrate with databases and APIs
Enable real-time data access for agents

Custom Tool Development: Create specialized tools using OpenAPI-style function specifications for enhanced agent capabilities.

How do I handle errors and troubleshooting?

Common Issues and Solutions:Authentication Errors:

Verify your API key is correct and active
Check that the x-api-key header is properly set (the Authorization: Bearer <key> header is also accepted)
Ensure your API key has the necessary permissions

Rate Limit Exceeded:

Implement exponential backoff for failed requests
Monitor your API usage to stay within limits
Consider upgrading to Premium for higher limits

Timeout Issues:

Increase request timeout values
Consider breaking complex tasks into smaller chunks
Use batch processing for multiple operations

Model Availability:

Check if your requested model is currently available
Have fallback models configured
Monitor model status through the health endpoint

What security features are available?

Enterprise Security:

API Key Authentication: Secure authentication for all requests
Rate Limiting: Prevents abuse and ensures fair usage
Data Encryption: All data is encrypted in transit and at rest
Access Controls: Granular permissions and access management

Best Practices:

Never commit API keys to version control
Use environment variables for all sensitive configuration
Implement proper access controls in production environments
Regularly rotate API keys

How can I get support?

Community Resources:

Documentation: docs.swarms.ai
Discord Community: Join Discord
Technical Blog: Medium

Professional Support:

Technical Support: Book Support Session
Enterprise Support: Contact through the platform
Onboarding Sessions: Book with Kye Gomez

Stay Updated:

Twitter: @kyegomez
LinkedIn: The Swarm Corporation
YouTube: Swarms Channel

Can I use Swarms for production applications?

Yes! The Swarms API is designed for production use with:

Scalability: Handle thousands of concurrent agents
Enterprise Features: Security, compliance, and governance
Monitoring: Comprehensive logging and analytics
Support: Professional support for production deployments

Production Best Practices:

Implement proper error handling and retry logic
Monitor API usage and costs
Use appropriate rate limiting strategies
Test thoroughly before deployment
Keep API keys secure and rotate regularly

What's the difference between single agents and swarms?

Single Agents:

Purpose: Focused tasks that don’t require collaboration
Use Cases: Simple Q&A, content generation, data analysis
Benefits: Fast, simple, cost-effective
Limitations: Limited to single perspective, no collaboration

Multi-Agent Swarms:

Purpose: Complex tasks requiring multiple perspectives or specialized skills
Use Cases: Research teams, medical analysis, financial forecasting
Benefits: Multiple perspectives, specialized expertise, parallel processing
Complexity: Higher setup and coordination requirements

How do I choose the right model for my use case?

Model Selection Guidelines:For Complex Analysis:

Use GPT-4 or Claude Sonnet 4 for tasks requiring deep reasoning
Higher token limits for comprehensive analysis

For Fast Responses:

Choose gpt-4.1-mini for quick, straightforward tasks
Lower costs for high-volume applications

For Creative Tasks:

Higher temperature settings (0.7-0.9) work better
GPT-4 or Claude models for creative content

For Factual Tasks:

Lower temperature settings (0.1-0.3) provide more consistent responses
Any model can work well with proper prompting

Can I integrate Swarms with my existing systems?

Yes! The Swarms API is designed for easy integration:Integration Options:

REST API: Standard HTTP endpoints for any language
Client Libraries: Official SDKs for Python, TypeScript, Go, Java
Webhooks: Real-time notifications for long-running tasks
Batch Processing: Process multiple requests efficiently

Common Integration Patterns:

Microservices: Deploy as independent services
API Gateway: Integrate with existing API infrastructure
Event-Driven: Trigger agents based on system events
Scheduled Tasks: Run agents on regular schedules

Getting Started

Clients

Agent Completions

Multi-Agent

Batch

Capabilities

Resources

Swarms Cloud

FAQ

Still Have Questions?

​Still Have Questions?

Still Have Questions?