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

Access to these endpoints is restricted to Pro and Ultra plans. To upgrade, see Pricing.

Premium Endpoints

Endpoint	Method	Description
`/v1/graph-workflow/completions`	POST	Execute graph workflows with directed agent nodes and edges. Enables complex multi-agent collaboration with parallel execution, automatic compilation, and comprehensive workflow orchestration.
`/v1/agent/batch/completions`	POST	Process multiple agent tasks in parallel batches with high-throughput batch processing capabilities. Ideal for large-scale document analysis, data processing, and enterprise-scale operations.
`/v1/swarm/batch/completions`	POST	Execute batch swarm completions with concurrent multi-agent execution for complex collaborative workflows at scale.
`/v1/reasoning-agent/completions`	POST	Execute advanced reasoning agent tasks using specialized reasoning architectures like self-consistency, majority voting, and iterative refinement for improved answer quality and reliability.
`/v1/batched-grid-workflow/completions`	POST	Execute multiple tasks across multiple agents in a grid pattern with parallel batch processing. Creates comprehensive task-agent matrices for comparative analysis and multi-perspective evaluation.

Why These Endpoints Require Premium Access

These endpoints are resource-intensive operations that provide:

High-throughput batch processing - Process hundreds of tasks concurrently
Concurrent multi-agent execution - Run multiple specialized agents simultaneously
Advanced reasoning capabilities - Utilize sophisticated reasoning architectures for complex problem-solving
Enterprise-scale workflow orchestration - Coordinate large-scale, multi-step agent workflows

Premium tier restrictions ensure sustainable infrastructure costs while maintaining quality service for enterprise customers.

Error Response for Free Tier Users

Free tier users attempting to access these endpoints will receive a 403 Forbidden error with upgrade instructions:

{
  "error": {
    "type": "premium_access_required",
    "message": "Premium subscription required",
    "detail": "Access to Batch Agent Completions requires a premium subscription. This feature allows you to process multiple agent tasks concurrently in a single request. Your current account is on the free tier, which does not include access to premium features. To unlock this and other premium capabilities, please upgrade your account at https://swarms.world/platform/account. Premium subscriptions provide access to high-throughput batch processing, concurrent execution, advanced reasoning agents, and enterprise-scale workflow orchestration.",
    "status_code": 403,
    "upgrade_url": "https://swarms.world/platform/account",
    "documentation": "https://docs.swarms.ai"
  }
}

The detail message is tailored per endpoint (naming the specific feature you tried to access).

Notes

These endpoints may have different rate limits aligned with premium tiers.
Ensure your API key is associated with a Pro, Ultra, or Premium subscription.
Premium endpoints are also billable: your account’s total credit balance must be above $1.00, or the request is rejected with a 402 Payment Required error before any work runs. Check your balance with GET /v1/account/credits.
Beyond these five endpoints, certain models (e.g. GPT-5, Claude 4 Opus/Sonnet, Gemini 2.5 Pro) are also gated to premium subscribers on regular endpoints like /v1/agent/completions and /v1/swarm/completions — see Pricing for the current list.
For endpoint schemas and examples, see related documentation pages.

​Premium Endpoints

​Why These Endpoints Require Premium Access

​Error Response for Free Tier Users

​Notes

Premium Endpoints

Why These Endpoints Require Premium Access

Error Response for Free Tier Users

Notes