Rate Limits

The Swarms API implements a comprehensive rate limiting system that tracks API requests across multiple time windows and enforces various limits to ensure fair usage and system stability.

Rate Limits Summary

Rate Limit Type	Free Tier	Premium Tier	Time Window	Description
Requests per Minute	100	2,000	1 minute	Maximum API calls per minute
Requests per Hour	50	10,000	1 hour	Maximum API calls per hour
Requests per Day	1,200	100,000	24 hours	Maximum API calls per day
Tokens per Agent	200,000	2,000,000	Per request	Maximum tokens per agent
Prompt Length	200,000	200,000	Per request	Maximum input tokens per request
Batch Size	10	10	Per request	Maximum agents in batch requests
IP-based Fallback	100	100	60 seconds	For requests without API keys

Detailed Rate Limit Explanations

1. Request Rate Limits

These limits control how many API calls you can make within specific time windows.

Per-Minute Limit

Tier	Requests per Minute	Reset Interval	Applies To
Free	100	Every minute (sliding)	All API endpoints
Premium	2,000	Every minute (sliding)	All API endpoints

Per-Hour Limit

• Free Tier: 50 requests per hour

• Premium Tier: 10,000 requests per hour

• Reset: Every hour (sliding window)

• Applies to: All API endpoints

Per-Day Limit

• Free Tier: 1,200 requests per day (50 × 24)

• Premium Tier: 100,000 requests per day

• Reset: Every 24 hours (sliding window)

• Applies to: All API endpoints

2. Token Limits

These limits control the amount of text processing allowed per request.

Tokens per Agent

• Free Tier: 200,000 tokens per agent

• Premium Tier: 2,000,000 tokens per agent

• Applies to: Individual agent configurations

• Includes: System prompts, task descriptions, and agent names

Prompt Length Limit

• All Tiers: 200,000 tokens maximum

• Applies to: Combined input text (task + history + system prompts)

• Error: Returns 400 error if exceeded

• Message: "Prompt is too long. Please provide a prompt that is less than 10000 tokens."

3. Batch Processing Limits

These limits control concurrent processing capabilities.

Batch Size Limit

• All Tiers: 10 agents maximum per batch

• Applies to: /v1/agent/batch/completions endpoint

• Error: Returns 400 error if exceeded

• Message: "ERROR: BATCH SIZE EXCEEDED - You can only run up to 10 batch agents at a time."

How Rate Limiting Works

Database-Based Tracking

The system uses a database-based approach for API key requests:

1. Request Logging: Every API request is logged to the swarms_api_logs table

2. Time Window Queries: The system queries for requests in the last minute, hour, and day

3. Limit Comparison: Current counts are compared against configured limits

4. Request Blocking: Requests are blocked if any limit is exceeded

Sliding Windows

Rate limits use sliding windows rather than fixed windows:

• Minute: Counts requests in the last 60 seconds

• Hour: Counts requests in the last 60 minutes

• Day: Counts requests in the last 24 hours

This provides more accurate rate limiting compared to fixed time windows.

Checking Your Rate Limits

API Endpoint

Use the /v1/rate/limits endpoint to check your current usage:

curl -H "x-api-key: your-api-key" \
     https://api.swarms.world/v1/rate/limits

Response Format

{
  "success": true,
  "rate_limits": {
    "minute": {
      "count": 5,
      "limit": 100,
      "exceeded": false,
      "remaining": 95,
      "reset_time": "2024-01-15T10:30:00Z"
    },
    "hour": {
      "count": 25,
      "limit": 50,
      "exceeded": false,
      "remaining": 25,
      "reset_time": "2024-01-15T11:00:00Z"
    },
    "day": {
      "count": 150,
      "limit": 1200,
      "exceeded": false,
      "remaining": 1050,
      "reset_time": "2024-01-16T10:00:00Z"
    }
  },
  "limits": {
    "maximum_requests_per_minute": 100,
    "maximum_requests_per_hour": 50,
    "maximum_requests_per_day": 1200,
    "tokens_per_agent": 200000
  },
  "timestamp": "2024-01-15T10:29:30Z"
}

Handling Rate Limit Errors

Error Response

When rate limits are exceeded, you'll receive a 429 status code:

{
  "detail": "Rate limit exceeded for minute window(s). Upgrade to Premium for increased limits (2,000/min, 10,000/hour, 100,000/day) at https://swarms.world/platform/account for just $99/month."
}

Best Practices

1. Monitor Usage: Regularly check your rate limits using the /v1/rate/limits endpoint

2. Implement Retry Logic: Use exponential backoff when hitting rate limits

3. Optimize Requests: Combine multiple operations into single requests when possible

4. Upgrade When Needed: Consider upgrading to Premium for higher limits

Premium Tier Benefits

Upgrade to Premium for significantly higher limits:

• 20x more requests per minute (2,000 vs 100)

• 200x more requests per hour (10,000 vs 50)

• 83x more requests per day (100,000 vs 1,200)

• 10x more tokens per agent (2M vs 200K)

Visit Swarms Platform Account to upgrade for just $99/month.

Performance Considerations

• Database queries are optimized to only count request IDs

• Rate limit checks are cached per request

• Fallback mechanisms ensure system reliability

• Minimal impact on request latency

• Persistent tracking across server restarts