You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
swarms/docs/swarms_cloud/rate_limits.md

5.8 KiB

Swarms API 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