Rate Limits & Quotas

Overview

Akhara enforces rate limits to ensure fair usage and system stability. Rate limits are applied per API key and vary by endpoint and plan tier.

Rate Limits

Default Limits by Plan

Plan	Requests/min	Requests/hour	Concurrent
Starter	60	1,000	5
Pro	300	10,000	20
Enterprise	1,000	50,000	100

Limits by Endpoint Category

Category	Starter	Pro	Enterprise
Read operations (GET)	100/min	500/min	2,000/min
Write operations (POST/PATCH)	60/min	300/min	1,000/min
Batch operations	10/min	50/min	200/min
Export operations	5/min	20/min	100/min
Evaluation runs	10/min	50/min	200/min

Endpoint-Specific Limits

Some endpoints have specific limits due to resource intensity:

Endpoint	Limit	Reason
`POST /v1/evaluations`	10/min	Compute-intensive
`POST /v1/datasets/{id}/samples` (batch)	20/min	Storage-intensive
`POST /v1/audit/reports`	5/min	Report generation
`GET /v1/audit/stream`	1 concurrent	SSE connection

Rate Limit Headers

Every API response includes rate limit information in headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when window resets
`X-RateLimit-Window`	Window duration in seconds
`Retry-After`	Seconds to wait before retrying (on 429)

Example Response Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 245
X-RateLimit-Reset: 1705327200
X-RateLimit-Window: 60

Example 429 Response

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705327200
Retry-After: 32
Content-Type: application/json

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 32 seconds.",
    "details": {
      "limit": 300,
      "window": "60s",
      "retry_after": 32
    }
  }
}

Usage Quotas

Quotas limit total usage over billing periods, separate from rate limits.

Quota Types by Plan

Quota	Starter	Pro	Enterprise
Samples stored	10,000	100,000	Unlimited
Evaluations/month	100	1,000	Unlimited
Samples evaluated/month	50,000	500,000	Unlimited
Human reviews/month	500	5,000	Unlimited
Reviewer seats	3	20	Unlimited
Projects	5	25	Unlimited
Data retention	90 days	1 year	7 years
Audit log retention	90 days	1 year	7 years

Checking Quota Usage

from akhara import Akhara

client = Akhara()

# Get current usage
usage = client.usage.get()

print(f"Samples: {usage.samples.current}/{usage.samples.limit}")
print(f"Evaluations: {usage.evaluations.current}/{usage.evaluations.limit}")
print(f"Reviews: {usage.reviews.current}/{usage.reviews.limit}")
print(f"Billing period: {usage.period_start} to {usage.period_end}")

curl "https://api.akhara.ai/v1/usage" \
  -H "Authorization: Bearer rb_live_xxxxxxxx"

Response

{
  "object": "usage",
  "plan": "pro",
  "period_start": "2024-01-01T00:00:00Z",
  "period_end": "2024-01-31T23:59:59Z",
  "samples": {
    "current": 45000,
    "limit": 100000,
    "percent_used": 45
  },
  "evaluations": {
    "current": 234,
    "limit": 1000,
    "percent_used": 23.4
  },
  "samples_evaluated": {
    "current": 156000,
    "limit": 500000,
    "percent_used": 31.2
  },
  "reviews": {
    "current": 1245,
    "limit": 5000,
    "percent_used": 24.9
  },
  "reviewers": {
    "current": 8,
    "limit": 20
  },
  "projects": {
    "current": 12,
    "limit": 25
  }
}

Handling Rate Limits

Basic Retry with Backoff

import time
from akhara import Akhara, RateLimitError

client = Akhara()

def call_with_retry(func, max_retries=5):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError as e:
            if attempt == max_retries - 1:
                raise
            
            wait_time = e.retry_after or (2 ** attempt)
            print(f"Rate limited. Waiting {wait_time}s...")
            time.sleep(wait_time)

# Usage
result = call_with_retry(
    lambda: client.datasets.list(project="proj_abc123")
)

Proactive Rate Limiting

Check remaining quota before making requests:

import time

class RateLimitedClient:
    def __init__(self, client):
        self.client = client
        self.remaining = None
        self.reset_at = None
    
    def request(self, func):
        # Wait if we're out of quota
        if self.remaining is not None and self.remaining <= 0:
            wait_time = self.reset_at - time.time()
            if wait_time > 0:
                time.sleep(wait_time)
        
        response = func()
        
        # Update from headers
        self.remaining = response.headers.get('X-RateLimit-Remaining')
        self.reset_at = response.headers.get('X-RateLimit-Reset')
        
        return response

Batch Operations

Reduce API calls by using batch endpoints:

# ❌ Bad: Many individual calls
for sample in samples:
    client.datasets.add_sample(dataset="ds_xyz", **sample)

# ✅ Good: Single batch call
client.datasets.add_samples(
    dataset="ds_xyz",
    samples=samples  # Up to 100 per batch
)

Parallel Requests with Limits

Control concurrency to stay within limits:

import asyncio
from akhara import AsyncAkhara

client = AsyncAkhara()
semaphore = asyncio.Semaphore(10)  # Max 10 concurrent

async def fetch_with_limit(sample_id):
    async with semaphore:
        return await client.datasets.get_sample(
            dataset="ds_xyz",
            sample=sample_id
        )

async def fetch_all(sample_ids):
    tasks = [fetch_with_limit(sid) for sid in sample_ids]
    return await asyncio.gather(*tasks)

# Run
samples = asyncio.run(fetch_all(sample_ids))

Quota Alerts

Configure alerts when approaching quota limits:

# Set up quota alerts
client.alerts.create(
    type="quota_warning",
    config={
        "metrics": ["samples", "evaluations", "reviews"],
        "threshold_percent": 80,  # Alert at 80% usage
        "channels": ["email", "slack"],
        "recipients": ["[email protected]"]
    }
)

Webhook Payload

{
  "event": "quota.threshold_reached",
  "timestamp": "2024-01-20T15:00:00Z",
  "data": {
    "metric": "evaluations",
    "current": 820,
    "limit": 1000,
    "percent_used": 82,
    "threshold": 80,
    "period_end": "2024-01-31T23:59:59Z"
  }
}

Requesting Limit Increases

Temporary Increases

For one-time events (e.g., large data migration):

# Request temporary limit increase
request = client.support.request_limit_increase(
    reason="One-time migration of 500k samples",
    requested_limits={
        "samples_per_batch": 500,
        "requests_per_minute": 1000
    },
    duration_hours=24,
    start_time="2024-02-01T00:00:00Z"
)

print(f"Request ID: {request.id}")
print(f"Status: {request.status}")  # pending, approved, denied

Permanent Increases

Contact sales for permanent limit increases:

Pro → Enterprise upgrade: Unlimited quotas
Custom enterprise limits: Tailored to your needs
Dedicated infrastructure: Isolated rate limits

Best Practices

Use Batch APIs

Combine multiple operations into batch requests when possible

Implement Backoff

Always implement exponential backoff for 429 responses

Cache Responses

Cache read results to reduce API calls

Monitor Usage

Set up alerts before hitting limits

Do’s and Don’ts

✅ Do	❌ Don’t
Use batch endpoints for bulk operations	Make individual calls in tight loops
Respect `Retry-After` header	Retry immediately after 429
Cache frequently accessed data	Fetch the same data repeatedly
Use webhooks for real-time updates	Poll for status changes
Pre-fetch data during low-traffic periods	Run bulk operations during peak hours

Errors & Status Codes

Handling API errors

Billing

Upgrade your plan

​Overview

​Rate Limits

​Default Limits by Plan

​Limits by Endpoint Category

​Endpoint-Specific Limits

​Rate Limit Headers

​Example Response Headers

​Example 429 Response

​Usage Quotas

​Quota Types by Plan

​Checking Quota Usage

​Response

​Handling Rate Limits

​Basic Retry with Backoff

​Proactive Rate Limiting

​Batch Operations

​Parallel Requests with Limits

​Quota Alerts

​Webhook Payload

​Requesting Limit Increases

​Temporary Increases

​Permanent Increases

​Best Practices