Rate Limits

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

Monitor Regularly: Check usage via /v1/key endpoint
Handle 429: Implement exponential backoff
Distribute Load: Use multiple models to maximize throughput
Set Alerts: Monitor balance and usage thresholds
Respect Limits: Don’t attempt to bypass rate limits

Getting Started

Features

API

Models

Use Cases

Community

Overview

Checking Limits

Query Parameters

Basic Request

Detailed Request

Response Format

Basic Response

Detailed Response

Response Fields

Usage Statistics

Rate Limit Behavior

429 Too Many Requests

Rate Limit Headers

Tier-Based Limits

Model-Specific Limits

Free Tier Limits

Negative Balance

DDoS Protection

Monitoring Usage

Programmatic Monitoring

Best Practices

See Also

​Overview

​Checking Limits

​Query Parameters

​Basic Request

​Detailed Request

​Response Format

​Basic Response

​Detailed Response

​Response Fields

​Usage Statistics

​Rate Limit Behavior

​429 Too Many Requests

​Rate Limit Headers

​Tier-Based Limits

​Model-Specific Limits

​Free Tier Limits

​Negative Balance

​DDoS Protection

​Monitoring Usage

​Programmatic Monitoring

​Best Practices

​See Also

Overview

Checking Limits

Query Parameters

Basic Request

Detailed Request

Response Format

Basic Response

Detailed Response

Response Fields

Usage Statistics

Rate Limit Behavior

429 Too Many Requests

Rate Limit Headers

Tier-Based Limits

Model-Specific Limits

Free Tier Limits

Negative Balance

DDoS Protection

Monitoring Usage

Programmatic Monitoring

Best Practices

See Also