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

Overview

GET /v1/rate/limits returns your current request counts for the last minute, hour, and day, the configured limits for your subscription tier, and your tier (free or premium). Use it to build usage dashboards or to back off before you hit 429 Too Many Requests.

Every authenticated response also carries live X-RateLimit-* headers (X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, -Hour, -Day, X-RateLimit-Reset, X-RateLimit-Tier), and a 429 response adds Retry-After. Reading those headers off any response is cheaper than calling this endpoint separately if you just need the current remaining count.

Step 1: Installation

pip install requests swarms-client python-dotenv

Step 2: API Key Setup

Set your API key in a .env file:

SWARMS_API_KEY=your_api_key_here

Step 3: Code Example

cURL
Python (requests)
swarms-client

curl -X GET "https://api.swarms.world/v1/rate/limits" \
  -H "x-api-key: $SWARMS_API_KEY" \
  -H "Content-Type: application/json"

import os
import json
import requests
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"

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

response = requests.get(f"{BASE_URL}/v1/rate/limits", headers=headers)
response.raise_for_status()
data = response.json()
print(json.dumps(data, indent=2))

minute = data["rate_limits"]["minute"]
print(f"Requests this minute: {minute['count']}/{minute['limit']} "
      f"({minute['remaining']} remaining, tier={data['tier']})")

import os
from swarms_client import SwarmsClient
from dotenv import load_dotenv

load_dotenv()

# Pass base_url explicitly so the SDK targets the documented API host
# (its built-in default points at an internal Cloud Run URL).
client = SwarmsClient(
    api_key=os.getenv("SWARMS_API_KEY"),
    base_url="https://api.swarms.world",
)

response = client.client.rate.get_limits()
print(response)

print(client.health.check())

Run the script to check your current rate limits and API health status.

Understanding the Response

{
  "success": true,
  "rate_limits": {
    "minute": {
      "count": 12,
      "limit": 100,
      "exceeded": false,
      "remaining": 88,
      "reset_time": "2026-09-14T12:01:00.000Z"
    },
    "hour": {
      "count": 340,
      "limit": 350,
      "exceeded": false,
      "remaining": 10,
      "reset_time": "2026-09-14T13:00:00.000Z"
    },
    "day": {
      "count": 900,
      "limit": 1200,
      "exceeded": false,
      "remaining": 300,
      "reset_time": "2026-09-15T00:00:00.000Z"
    }
  },
  "limits": {
    "maximum_requests_per_minute": 100,
    "maximum_requests_per_hour": 350,
    "maximum_requests_per_day": 1200,
    "tokens_per_agent": 200000
  },
  "tier": "free",
  "timestamp": "2026-09-14T12:00:30.000Z"
}

Field	Type	Description
`success`	boolean	Whether the request succeeded
`rate_limits`	object	`minute`, `hour`, `day` windows, each with `count`, `limit`, `exceeded`, `remaining`, `reset_time`
`limits`	object	The configured limits for your tier: `maximum_requests_per_minute`, `maximum_requests_per_hour`, `maximum_requests_per_day`, `tokens_per_agent`
`tier`	string	Your current subscription tier: `free` or `premium`
`timestamp`	string	ISO timestamp when this snapshot was generated

Default limits by tier (api/schemas.py RateLimitsFreeTier / RateLimitsPremiumTier):

Tier	Per minute	Per hour	Per day	Tokens per agent
`free`	100	350	1,200 (`50 * 24`)	200,000
`premium`	2,000	10,000	100,000	2,000,000

A user is on the premium tier if their account has an active subscription or a pro/ultra/premium tier on file; otherwise they’re on free. If the tier lookup fails internally, the API falls open to the free-tier limits rather than blocking the request.

Getting Started

MCP Server Tutorials

Agent Capabilities

Multi-Agent Architectures

Finance & Investing

Healthcare & Life Sciences

Legal, M&A & Diligence

Customer Operations

Defense, Gov & Supply Chain

Marketing, Content & Founder Tools

API Utilities

Migration Guides

Resources

Production

Compatibility & Benchmarks

Tutorials & Integrations

Rate Limits Example

Overview

Step 1: Installation

Step 2: API Key Setup

Step 3: Code Example

Understanding the Response

​Overview

​Step 1: Installation

​Step 2: API Key Setup

​Step 3: Code Example

​Understanding the Response

Overview

Step 1: Installation

Step 2: API Key Setup

Step 3: Code Example

Understanding the Response