Quota Management

This guide explains the quota system in detail.

Quota Overview

Quota represents your available API usage credits. Every API request consumes quota based on token usage and model pricing.

Request → Token Count → Model Multiplier → Quota Consumed

Types of Quota

1. API Key Quota

Each API key has its own quota allocation:

2. Subscription Quota

Subscription plans include monthly quota that resets each billing cycle:

3. Account Balance

Your account balance for Pay-As-You-Go (PAYG) usage:

Quota Calculation

Subscription Quota — Per-Request Billing

Subscription plans use a per-request billing model. Each API request consumes a fixed amount of quota based on the model's multiplier rate:

Quota Consumed per Request = Model Rate (fixed multiplier)

This is independent of token usage — a short response and a long response cost the same quota for the same model. Different plans offer different rates for the same model — higher-tier plans have lower multipliers, giving you more requests per quota.

PAYG — Per-Token Billing

PAYG (Pay-As-You-Go) uses a per-token billing model. Each request is charged based on actual token consumption:

Cost = (Input Tokens × Input Rate) + (Output Tokens × Output Rate)

Model Pricing

For current model rates and pricing, visit the Subscribe page.

Monitoring Quota Usage

Dashboard Overview

View your quota status in the dashboard:

1. Account Overview - Total balance and usage
2. API Keys - Per-key quota status
3. Subscription - Cycle quota remaining
4. Usage History - Detailed consumption logs

API Endpoints

Check quota programmatically:

import requests

response = requests.get(
    "https://api.apertis.ai/v1/dashboard/billing/credits",
    headers={"Authorization": "Bearer sk-your-api-key"}
)

credits = response.json()
payg = credits["payg"]

if payg["token_is_unlimited"]:
    print("Token quota: unlimited")
else:
    print(f"Remaining token credits: ${payg['token_remaining']:.2f}")
    print(f"Used token credits: ${payg['token_used']:.2f}")

if credits["is_subscriber"]:
    subscription = credits["subscription"]
    print(f"Cycle quota remaining: {subscription['cycle_quota_remaining']}")

Response Headers

API responses include usage information:

{
  "usage": {
    "prompt_tokens": 50,
    "completion_tokens": 100,
    "total_tokens": 150
  }
}

Managing Quota Effectively

1. Choose the Right Model

Match model capabilities to your needs:

2. Optimize Prompts

Reduce token usage with efficient prompts:

# Inefficient (high token usage)
prompt = """
I would like you to please help me with the following task.
I need you to summarize the following text for me.
Please make sure the summary is comprehensive and detailed.
Here is the text:
{long_text}
"""

# Efficient (lower token usage)
prompt = f"Summarize:\n{long_text}"

3. Use System Messages Wisely

System messages persist across turns. Keep them concise:

# Good - concise system message
messages = [
    {"role": "system", "content": "You are a helpful coding assistant."},
    {"role": "user", "content": "..."}
]

# Avoid - overly detailed system message
messages = [
    {"role": "system", "content": "You are an extremely helpful assistant..."},  # 500+ tokens
    {"role": "user", "content": "..."}
]

4. Implement Caching

Cache responses for identical queries:

import hashlib
from functools import lru_cache

@lru_cache(maxsize=1000)
def get_cached_response(prompt_hash, model):
    return client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": prompt}]
    )

# Create hash for caching
prompt_hash = hashlib.md5(prompt.encode()).hexdigest()
response = get_cached_response(prompt_hash, "gpt-5.5")

5. Set Quota Limits

Configure API key quota limits to prevent overspending:

1. Go to API Keys in dashboard
2. Edit the key
3. Set Quota Limit
4. Save changes

Quota Alerts

Setting Up Alerts

Configure alerts to be notified when quota is low:

1. Navigate to Settings → Notifications
2. Enable Low Quota Warning
3. Set threshold percentage (e.g., 20%)
4. Choose notification method (email)

Alert Thresholds

Quota Exhaustion

What Happens

When quota is exhausted:

1. API Key Quota: Requests return 402 Payment Required
2. Subscription Quota: Falls back to PAYG per-token billing (if enabled), otherwise returns 402
3. Account Balance: All requests fail with 402

Error Response

{
  "error": {
    "message": "You have exceeded your quota",
    "type": "billing_error",
    "code": "quota_exceeded"
  }
}

Recovery Options

Quota Reset

Subscription Quota Reset

Subscription quota resets automatically at the start of each billing cycle:

Cycle Start (e.g., Jan 1) → Full Quota Available
                          ↓
                    Use Throughout Month
                          ↓
Cycle End (e.g., Jan 31) → Unused Quota Expires
                          ↓
Next Cycle (Feb 1)       → Full Quota Restored

Manual Quota Reset (Admin)

Account administrators can reset quota for:

• Individual API keys
• Subscription cycles
• User accounts

Best Practices

For Development

1. Use separate keys for development and production
2. Set low limits on development keys
3. Monitor usage during testing
4. Use cheaper models for development

For Production

1. Set appropriate limits based on expected usage
2. Enable auto top-up to prevent service interruption
3. Monitor alerts and respond quickly
4. Review usage regularly for optimization opportunities

Cost Control Strategies

Usage Reports

Accessing Reports

View detailed usage reports in the dashboard:

1. Go to Usage → Reports
2. Select date range
3. Filter by model, key, or endpoint
4. Export as CSV if needed

Report Metrics

Related Topics

• Subscription Plans - Plan quotas and features
• Rate Limits - Request rate limits
• PAYG - Pay-As-You-Go billing
• API Keys - Key management