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

# Rate Limits

> Rate limits, quotas, and usage tracking

## Overview

Rate limits are tier-based and applied per API key. Limits vary by account tier and model. Creating additional accounts or keys does not bypass global capacity limits.

## Checking Limits

Query your API key status:

```
GET https://api.anannas.ai/v1/key
```

### Query Parameters

* `details=true`: Include detailed usage statistics

### Basic Request

```python theme={null}
import requests

response = requests.get(
  "https://api.anannas.ai/v1/key",
  headers={"Authorization": "Bearer <ANANNAS_API_KEY>"}
)

data = response.json()
print(f"Usage: {data['data']['usage']}")
print(f"Limit: {data['data']['limit']}")
```

### Detailed Request

```python theme={null}
response = requests.get(
  "https://api.anannas.ai/v1/key?details=true",
  headers={"Authorization": "Bearer <ANANNAS_API_KEY>"}
)

data = response.json()
print(f"Balance: {data['data']['balance']}")
print(f"Usage stats: {data['data']['usage_stats']}")
```

## Response Format

### Basic Response

```json theme={null}
{
  "data": {
    "created_at": "2024-01-01T00:00:00Z",
    "is_active": true,
    "is_org_key": true,
    "label": "Main Key",
    "last_used": "2024-01-15T10:30:00Z",
    "limit": 1000,
    "name": "My API Key",
    "org_id": "691744a8236e7e5afac6564c",
    "org_name": "My Organization",
    "tier": "tier2",
    "tier_name": "Standard",
    "usage": 120.5
  }
}
```

### Detailed Response

With `details=true`:

```json theme={null}
{
  "data": {
    "account_type": "organization",
    "balance": 112.85,
    "created_at": "2024-01-01T00:00:00Z",
    "is_active": true,
    "is_org_key": true,
    "label": "Main Key",
    "last_used": "2024-01-15T10:30:00Z",
    "limit": 1000,
    "name": "My API Key",
    "org_id": "691744a8236e7e5afac6564c",
    "org_name": "My Organization",
    "tier": "tier2",
    "tier_name": "Standard",
    "usage": 120.5,
    "usage_stats": {
      "last_30_days": {
        "cost": 0.11,
        "requests": 16
      },
      "last_7_days": {
        "cost": 0.11,
        "requests": 16
      }
    }
  }
}
```

## Response Fields

| Field          | Type             | Description                                 |
| -------------- | ---------------- | ------------------------------------------- |
| `usage`        | `number`         | Total credits used (float)                  |
| `limit`        | `number \| null` | Credit limit (null if unlimited)            |
| `balance`      | `number`         | Current account balance (details only)      |
| `account_type` | `string`         | `"organization"` or `"user"` (details only) |
| `tier`         | `string`         | Tier identifier (e.g., `"tier2"`)           |
| `tier_name`    | `string`         | Human-readable tier name                    |
| `org_id`       | `string`         | Organization ID (if applicable)             |
| `org_name`     | `string`         | Organization name (if applicable)           |
| `is_org_key`   | `boolean`        | Whether this is an organization-level key   |
| `is_active`    | `boolean`        | Whether the key is active                   |
| `label`        | `string`         | Optional key label                          |
| `name`         | `string`         | Key name                                    |
| `created_at`   | `string`         | ISO 8601 timestamp                          |
| `last_used`    | `string`         | ISO 8601 timestamp                          |
| `usage_stats`  | `object`         | Usage statistics (details only)             |

### Usage Statistics

`usage_stats` contains:

* `last_7_days`: Object with `cost` and `requests`
* `last_30_days`: Object with `cost` and `requests`

## Rate Limit Behavior

### 429 Too Many Requests

When rate limits are exceeded:

```json theme={null}
{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error"
  }
}
```

### Rate Limit Headers

Responses may include rate limit headers (if supported):

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1694268190
```

## Tier-Based Limits

Limits vary by account tier:

* **Free Tier**: Lower limits, daily caps
* **Standard (Tier 2)**: Higher limits
* **Enterprise**: Custom limits

Check your tier via the `/v1/key` endpoint.

## Model-Specific Limits

Different models may have different rate limits. Distribute usage across models if needed to maximize throughput.

## Free Tier Limits

Free-tier models have additional restrictions:

* Daily request caps
* Per-minute request limits
* Model availability restrictions

## Negative Balance

If account balance is below zero, all requests (including free-tier) fail with `402 Payment Required` until credits are added.

## DDoS Protection

Excessive request bursts may be blocked. Implement:

* Request throttling
* Exponential backoff
* Rate limit monitoring

## Monitoring Usage

### Programmatic Monitoring

```python theme={null}
import requests
import time

def check_usage(api_key):
  response = requests.get(
    "https://api.anannas.ai/v1/key?details=true",
    headers={"Authorization": f"Bearer {api_key}"}
  )
  data = response.json()["data"]
  
  usage_pct = (data["usage"] / data["limit"]) * 100 if data["limit"] else 0
  print(f"Usage: {data['usage']}/{data['limit']} ({usage_pct:.1f}%)")
  print(f"Balance: ${data['balance']:.2f}")
  
  return data

# Monitor every 5 minutes
while True:
  check_usage(api_key)
  time.sleep(300)
```

## Best Practices

1. **Monitor Regularly**: Check usage via `/v1/key` endpoint
2. **Handle 429**: Implement exponential backoff
3. **Distribute Load**: Use multiple models to maximize throughput
4. **Set Alerts**: Monitor balance and usage thresholds
5. **Respect Limits**: Don't attempt to bypass rate limits

## See Also

* [Authentication](/API/Authentication) - API key management
* [Errors](/API/errors) - Error handling