Usage Limits Guide
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Control your API spending with Freddy's three-tier limit hierarchy. Set organization-wide budgets, allocate specific amounts to API usage, and manage individual API key limits.

Overview

Freddy provides three levels of spending control:

Organization Limit - Total monthly spending cap across all usage types
Total API Key Limit - Combined monthly spending cap for all API keys
Individual API Key Limit - Monthly spending cap for a specific API key

This hierarchy allows you to allocate budgets flexibly while maintaining control over costs.

Limit Hierarchy

Organization Limit: 10,000 CHF (Broadest)
├── Total API Key Limit: 7,000 CHF (Medium)
│   ├── Production Key: 5,000 CHF
│   ├── Dev Key: 2,000 CHF
│   └── Test Key: 1,000 CHF
└── Other Org Spending: 3,000 CHF available

How Limits Are Enforced

When processing a request, Freddy checks limits in this order:

Organization Limit - Is total organization spending below the limit?
Total API Key Limit - Is combined API key spending below the limit?
Individual API Key Limit - Is this specific API key below its limit?

If any limit is exceeded, the request is rejected with a 429 error.

Setting Up Limits

Initial Setup

Start by setting your organization limit, then allocate a portion to API usage:

# Set organization limit to 10,000 CHF
curl -X PUT "https://api.aitronos.com/v1/analytics/usage/limits/org_abc123" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "monthly_api_limit": 10000.00
  }'

# Allocate 7,000 CHF to API keys (70% of budget)
curl -X PUT "https://api.aitronos.com/v1/analytics/usage/limits/org_abc123" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "total_api_key_limit": 7000.00
  }'

Setting Individual Key Limits

Distribute the total API key budget across your keys:

# Production key: 5,000 CHF
curl -X PUT "https://api.aitronos.com/v1/analytics/usage/limits/org_abc123" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key_id": "apikey_prod123",
    "api_key_limit": 5000.00
  }'

# Development key: 2,000 CHF
curl -X PUT "https://api.aitronos.com/v1/analytics/usage/limits/org_abc123" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key_id": "apikey_dev456",
    "api_key_limit": 2000.00
  }'

Monitoring Usage

Check Current Status

curl "https://api.aitronos.com/v1/analytics/usage/limits/org_abc123" \
  -H "X-API-Key: $FREDDY_API_KEY"

Response:

{
  "organization_limits": {
    "monthly_limit": 10000.00,
    "current_usage": 8250.50,
    "utilization_percentage": 82.51,
    "remaining_budget": 1749.50,
    "status": "warning"
  },
  "api_limits": {
    "monthly_limit": 7000.00,
    "current_usage": 6250.50,
    "utilization_percentage": 89.29,
    "remaining_budget": 749.50,
    "status": "warning"
  },
  "api_key_limits": [
    {
      "api_key_id": "apikey_prod123",
      "api_key_name": "Production Key",
      "monthly_limit": 5000.00,
      "current_usage": 4500.00,
      "utilization_percentage": 90.00,
      "status": "warning"
    }
  ],
  "summary": {
    "total_keys": 3,
    "keys_with_limits": 2,
    "keys_exceeded": 0,
    "overall_status": "warning"
  }
}

Understanding Status Values

ok - Utilization below 80% (healthy)
warning - Utilization between 80-100% (approaching limit)
exceeded - Utilization at or above 100% (requests blocked)
no_limit - No limit configured (unlimited spending)

Common Scenarios

Scenario 1: Allocating Budget to API Usage

You want to reserve 70% of your organization budget for API usage:

curl -X PUT "https://api.aitronos.com/v1/analytics/usage/limits/org_abc123" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "monthly_api_limit": 10000.00,
    "total_api_key_limit": 7000.00
  }'

This leaves 3,000 CHF for non-API spending (web usage, etc.).

Scenario 2: Handling Limit Exceeded Errors

When a limit is exceeded, requests return a 429 error:

{
  "success": false,
  "error": {
    "code": "SPENDING_LIMIT_EXCEEDED",
    "message": "Total API key monthly spending limit exceeded",
    "type": "client_error",
    "status": 429,
    "details": {
      "limit_type": "total_api_key",
      "usage": 7250.50,
      "limit": 7000.00,
      "utilization": 103.58
    }
  }
}

Resolution Options:

Wait for monthly reset - Limits reset on the 1st of each month
Increase the limit - Update total_api_key_limit to a higher value
Optimize usage - Review and reduce API consumption

Scenario 3: Increasing Limits Mid-Month

If you need more budget:

# Increase organization limit first
curl -X PUT "https://api.aitronos.com/v1/analytics/usage/limits/org_abc123" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "monthly_api_limit": 15000.00
  }'

# Then increase total API key limit
curl -X PUT "https://api.aitronos.com/v1/analytics/usage/limits/org_abc123" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "total_api_key_limit": 10000.00
  }'

Important: Always increase the organization limit before increasing the total API key limit to avoid validation errors.

Scenario 4: Removing a Total API Key Limit

To effectively disable the total API key limit, set it to a very high value:

curl -X PUT "https://api.aitronos.com/v1/analytics/usage/limits/org_abc123" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "total_api_key_limit": 999999.00
  }'

Monthly Reset

Automatic Reset Behavior

When: 1st day of each month at 00:00:00 UTC
What Resets: Usage counters and cache entries
What Persists: Configured limit values

Example Timeline

November 2025:
- Total API Key Limit: 7,000 CHF
- Usage: 7,250 CHF (exceeded)
- Status: Requests blocked

December 1, 2025 (00:00:00 UTC):
- Total API Key Limit: 7,000 CHF (unchanged)
- Usage: 0 CHF (reset)
- Status: Requests allowed

Best Practices

1. Set Appropriate Limits

Recommended Approach:

Review historical usage data
Set total API key limit to 70-80% of organization limit
Leave buffer for non-API spending
Monitor utilization for the first month

Example:

Organization Limit: 10,000 CHF
Total API Key Limit: 7,000 CHF (70%)
Buffer for other spending: 3,000 CHF (30%)

2. Monitor and Alert

Key Metrics:

utilization_percentage - Track approaching limits
remaining_budget - Monitor available spending
status - Watch for "warning" or "exceeded" states

Recommended Alert Thresholds:

80% utilization - Warning alert
95% utilization - Critical alert
100% utilization - Limit exceeded

3. Handle Limit Exceeded Scenarios

When Total API Key Limit is Exceeded:

Immediate Actions:
- Requests are automatically blocked
- Error responses include current usage and limit
- Cache is updated to prevent database load
Resolution Steps:
- Review current usage via GET endpoint
- Increase limit if budget allows
- Optimize API usage patterns
- Wait for monthly reset if near month end
Prevention:
- Set up monitoring alerts
- Review usage trends regularly
- Adjust limits proactively

4. Validation Rules

Remember:

total_api_key_limit must not exceed monthly_api_limit
All limits must be positive numbers (> 0)
Updates are atomic (all succeed or all fail)

Troubleshooting

Issue: Limit Update Rejected

Error: "Total API key limit cannot exceed organization limit"

Solution: Increase organization limit first, then total API key limit:

# Step 1: Increase organization limit
curl -X PUT ".../limits/org_abc123" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"monthly_api_limit": 15000.00}'

# Step 2: Increase total API key limit
curl -X PUT ".../limits/org_abc123" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"total_api_key_limit": 10000.00}'

Issue: Unexpected Limit Exceeded Errors

Symptom: Requests blocked even though usage seems below limit

Possible Causes:

Viewing wrong month's data
Cache not yet updated after limit increase
Multiple API keys contributing to aggregate

Solution:

# Check current month usage
curl "https://api.aitronos.com/v1/analytics/usage/limits/org_abc123?month=11&year=2025" \
  -H "X-API-Key: $FREDDY_API_KEY"

# Verify all API key usage in the response
# Check api_key_limits array for all keys

Issue: Limit Not Enforcing

Symptom: Requests allowed even when limit should be exceeded