Skip to main content

​
Rate Limits Summary

Rate Limit TypeFree TierPremium TierTime WindowDescription
Requests per Minute1002,0001 minuteMaximum API calls per minute
Requests per Hour5010,0001 hourMaximum API calls per hour
Requests per Day1,200100,00024 hoursMaximum API calls per day
Tokens per Agent200,0002,000,000Per requestMaximum tokens per agent
Prompt Length200,000200,000Per requestMaximum input tokens per request
Batch Size1010Per requestMaximum agents in batch requests
IP-based Fallback10010060 secondsFor 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

TierRequests per MinuteReset IntervalApplies To
Free100Every minute (sliding)All API endpoints
Premium2,000Every 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
⌘I