Rate Limits

​

Rate Limits Summary

​

Detailed Rate Limit Explanations

​

1. Request Rate Limits

​

Per-Minute Limit

​

Per-Hour Limit

• Free Tier: 350 requests per hour
• Premium Tier: 10,000 requests per hour
• Reset: Every hour (sliding window)
• Enforced on: All API endpoints (only completed billable requests count)

​

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)
• Enforced on: All API endpoints (only completed billable requests count)

​

2. Token Limits

​

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

• Free Tier: 200,000 tokens maximum
• Premium Tier: 2,000,000 tokens maximum
• Applies to: Combined input text (task + history + system prompts) — this uses the same per-tier tokens_per_agent limit as above
• Error: Returns 400 error if exceeded
• Message: “Prompt is too long. Please provide a prompt that is less than 200,000 tokens.” (limit reflects your tier)

​

3. Batch Processing Limits

​

Batch Size Limit

• Limit: 10 agent tasks maximum per batch
• Applies to: /v1/agent/batch/completions only (/v1/swarm/batch/completions has no fixed batch-size cap)
• 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

1. Request Logging: Completed billable work is logged to the swarms_api_logs table with the completion category
2. Time Window Queries: The system counts completion rows in the last minute, hour, and day. Telemetry and input rows are deliberately excluded, so GET endpoints and work that never completed do not increment your counters — each completed swarm, agent, or workflow run counts exactly once
3. Limit Comparison: Current counts are compared against configured limits
4. Request Blocking: Requests are blocked if any limit is exceeded — the limits are enforced on all endpoints, even though only completed billable requests count toward them

​

Sliding 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

​

Checking Your Rate Limits

​

API Endpoint

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": 350,
      "exceeded": false,
      "remaining": 325,
      "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": 350,
    "maximum_requests_per_day": 1200,
    "tokens_per_agent": 200000
  },
  "tier": "free",
  "timestamp": "2024-01-15T10:29:30Z"
}

​

Rate Limit Headers

​

Handling Rate Limit Errors

​

Error Response

{
  "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

• 20x more requests per minute (2,000 vs 100)
• ~29x more requests per hour (10,000 vs 350)
• 83x more requests per day (100,000 vs 1,200)
• 10x more tokens per agent (2M vs 200K)