# Usage Limits Guide

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:

1. **Organization Limit** - Total monthly spending cap across all usage types
2. **Total API Key Limit** - Combined monthly spending cap for all API keys
3. **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:

1. **Organization Limit** - Is total organization spending below the limit?
2. **Total API Key Limit** - Is combined API key spending below the limit?
3. **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:


```bash
# 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:


```bash
# 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


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

**Response:**


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


```bash
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:


```json
{
  "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:**

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


### Scenario 3: Increasing Limits Mid-Month

If you need more budget:


```bash
# 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:


```bash
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:**

1. **Immediate Actions:**
  - Requests are automatically blocked
  - Error responses include current usage and limit
  - Cache is updated to prevent database load
2. **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
3. **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:


```bash
# 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:**

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


**Solution:**


```bash
# 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

**Possible Causes:**

1. No limit configured (returns null)
2. Limit set to 0 (treated as disabled)
3. Checking wrong organization


**Solution:**


```bash
# Verify limit is set
curl "https://api.aitronos.com/v1/analytics/usage/limits/org_abc123" \
  -H "X-API-Key: $FREDDY_API_KEY"

# Check that api_limits.monthly_limit is not null or 0
```

## Related Documentation

- [Get usage limits](/docs/api-reference/analytics/usage/limits)
- [Update spending limits](/docs/api-reference/analytics/usage/update-limits)
- [Analytics Overview](/docs/api-reference/analytics/introduction)
- [API Key Management](/docs/api-reference/organizations/management/api-keys/create)