> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarms.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Get answers to the most common questions about the Swarms API platform, pricing, capabilities, and implementation.

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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).
  </Accordion>

  <Accordion title="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 <a href="/docs/documentation/resources/pricing">Pricing</a> page.
  </Accordion>

  <Accordion title="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)
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="How do I get started?">
    **1. Get Your API Key**
    Visit [Swarms Platform](https://swarms.world/platform/api-keys) to get your free API key.

    **2. Install Client Libraries**

    ```bash theme={null}
    # Python
    pip install swarms-client

    # JavaScript/TypeScript
    npm install axios dotenv
    ```

    **3. Make Your First API Call**

    ```python theme={null}
    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)
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="How can I get support?">
    **Community Resources:**

    * **Documentation**: [docs.swarms.ai](https://docs.swarms.ai/)
    * **Discord Community**: [Join Discord](https://discord.gg/EamjgSaEQf)
    * **Technical Blog**: [Medium](https://medium.com/@kyeg)

    **Professional Support:**

    * **Technical Support**: [Book Support Session](https://cal.com/swarms/swarms-technical-support)
    * **Enterprise Support**: Contact through the platform
    * **Onboarding Sessions**: [Book with Kye Gomez](https://cal.com/swarms/swarms-onboarding-session)

    **Stay Updated:**

    * **Twitter**: [@kyegomez](https://twitter.com/kyegomez)
    * **LinkedIn**: [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation)
    * **YouTube**: [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ)
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

***

## Still Have Questions?

If you don't see your question answered here, we're here to help:

* **Join our Discord**: [discord.gg/EamjgSaEQf](https://discord.gg/EamjgSaEQf)
* **Book Technical Support**: [cal.com/swarms/swarms-technical-support](https://cal.com/swarms/swarms-technical-support)

*Built with dedication by [The Swarm Corporation](https://swarms.ai)*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.