Skip to main content

Features

  • Type Safety: Full type definitions for all request params and response fields
  • Dual Clients: Both synchronous and asynchronous clients powered by httpx
  • Comprehensive Coverage: Access to all Swarms API endpoints
  • Modern Python: Built for Python 3.8+ with async/await support
  • Environment Integration: Seamless .env file support for API keys

Installation

Environment Setup

Create a .env file in your project root:

Quick Start

Your First Swarm

Client Configuration

Environment Variable

Set SWARMS_API_KEY in your environment (or a .env file), then load it in your code:

Direct API Key

Custom Configuration

If base_url is omitted, the installed swarms-client falls back to its own built-in default host rather than https://api.swarms.world. Always pass base_url="https://api.swarms.world" explicitly to avoid depending on whatever host ships baked into a given SDK version.

Core Operations

Single Agent Completion

Swarm Management

client.swarms.get_logs() calls GET /v1/swarm/logs, a deprecated alias. The canonical endpoint, GET /v1/account/logs, is not yet exposed on this SDK resource; call it directly with requests — see Endpoints Not Yet in the SDK below. On the Free plan both return only your 50 newest logs from the last 7 days; Pro returns up to 5,000 from the last 90 days. See Request Logs.

Model Information

Each entry is an object with the model id and its price per 1M input and output tokens, service fee included. A free-tier key’s list leaves out the premium-only models: every groq/* model and the frontier models listed under Premium-Only Models. Requesting one with a free-tier key returns 403.

Health and Status

Advanced Usage

Asynchronous Operations

Batch Operations

POST /v1/swarm/batch/completions and POST /v1/agent/batch/completions are premium-only endpoints. Calling them on a free-tier API key returns an error. See Premium Endpoints.
Run several swarms concurrently in a single request with client.swarms.batch.run:
The single-agent equivalent, client.agent.batch.run, takes a list of {"agent_config": ..., "task": ...} objects and posts to /v1/agent/batch/completions (batch limit: 50 agent completions per request):
If you are on the free tier, run tasks sequentially against the non-premium client.swarms.run or client.agent.run instead:

Helper Methods

The client provides convenient helper methods for common operations:

Examples

Content Generation Swarm

Data Analysis Pipeline

Endpoints Not Yet in the SDK

The installed swarms-client (0.8.0) wraps a subset of the Swarms API: client.agent.run, client.agent.batch.run, client.swarms.run, client.swarms.batch.run, client.swarms.get_logs, client.swarms.check_available, client.models.list_available, client.health.check, and client.client.rate.get_limits. Newer endpoints — reasoning agents, graph workflows, batched grid workflows, the auto agent builder, and the account/usage endpoints — are not yet wrapped by a dedicated resource. Call them directly with requests using the same x-api-key header:
The OpenAI-compatible endpoints (/v1/chat/completions, /v1/models) also work as a drop-in with the official openai Python SDK: pass base_url="https://api.swarms.world/v1" and api_key=os.getenv("SWARMS_API_KEY") to OpenAI(...).

Troubleshooting

Common Issues

  1. API Key Errors: Ensure your API key is valid and properly set in environment variables
  2. Rate Limiting: Check rate limits with client.client.rate.get_limits()
  3. Network Issues: Verify your internet connection and firewall settings
  4. Model Availability: Use client.models.list_available() to check available models

Getting Help