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

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

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

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

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

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

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 key management
• Errors - Error handling