> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarms.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 completed billable requests per minute                        |
| **Requests per Hour**   | 350       | 10,000       | 1 hour      | Maximum completed billable requests per hour                          |
| **Requests per Day**    | 1,200     | 100,000      | 24 hours    | Maximum completed billable requests per day                           |
| **Tokens per Agent**    | 200,000   | 2,000,000    | Per request | Maximum tokens per agent                                              |
| **Prompt Length**       | 200,000   | 2,000,000    | Per request | Maximum input tokens per request (same limit as tokens per agent)     |
| **Batch Size**          | 10        | 10           | Per request | Maximum tasks per agent batch request (`/v1/agent/batch/completions`) |
| **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         | Enforced On                                                |
| ------- | ------------------- | ---------------------- | ---------------------------------------------------------- |
| Free    | 100                 | Every minute (sliding) | All API endpoints (only completed billable requests count) |
| Premium | 2,000               | Every minute (sliding) | All API endpoints (only completed billable requests count) |

#### **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**

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**

* **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**

These limits control concurrent processing capabilities.

<Note>
  **Premium Access Required**: Batch endpoints (`/v1/agent/batch/completions`, `/v1/swarm/batch/completions`) are available only on Pro, Ultra, and Premium plans. See [Premium Endpoints](/docs/documentation/resources/premium-endpoints).
</Note>

#### **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

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

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

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:

```bash theme={null}
curl -H "x-api-key: your-api-key" \
     https://api.swarms.world/v1/rate/limits
```

### Response Format

```json theme={null}
{
  "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

Every rate-limited response also includes `X-RateLimit-*` headers (per-minute and per-day limits, remaining counts, reset time, and your tier), so you can track usage without an extra API call — see [Rate Limit Headers](/docs/documentation/resources/rate-limit-headers).

## Handling Rate Limit Errors

### Error Response

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

```json theme={null}
{
  "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)

* **\~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)

Visit [Swarms Platform Account](https://swarms.world/platform/account) to upgrade for just \$99/month.