# Get usage limits

Retrieve comprehensive usage limits information for an organization, including organization-level limits, total API key limits, and per-API-key breakdowns.

## Limit Hierarchy

The system enforces a three-tier limit hierarchy:

1. **Organization Limit** - Total spending across all usage types (broadest)
2. **Total API Key Limit** - Combined spending of all API keys (medium)
3. **Individual API Key Limit** - Spending for a specific API key (narrowest)


When processing requests, limits are checked in this order. If any limit is exceeded, the request is rejected with a 429 error.

#### Path Parameters

**`org_id`** string required

The organization ID (format: `org_<uuid>`).

#### Query Parameters

**`month`** integer optional

Month to query (1-12). Defaults to current month.

**`year`** integer optional

Year to query. Defaults to current year.

## Returns

Returns comprehensive usage limits information including organization limits, total API key limits, per-API-key breakdowns, and summary statistics.

### Response Fields

**`organization_limits`** object

Organization-level spending limits and usage.

**`api_limits`** object

Total API key spending limits and aggregate usage across all API keys. Returns `null` if no total API key limit is configured.

**`api_key_limits`** array

Individual API key limits and usage for each key in the organization.

**`summary`** object

Summary statistics including total keys, keys with limits, and overall status.

### Status Values

- `ok`: Utilization < 80%
- `warning`: 80% ≤ utilization < 100%
- `exceeded`: Utilization ≥ 100%
- `no_limit`: No limit configured



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


```python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]
org_id = "org_abc123"

response = requests.get(
    f"https://api.aitronos.com/v1/analytics/usage/limits/{org_id}",
    headers={"X-API-Key": api_key}
)

data = response.json()
print(f"Organization status: {data['organization_limits']['status']}")
print(f"Current usage: CHF {data['organization_limits']['current_usage']}")
```


```javascript
const response = await fetch(
  "https://api.aitronos.com/v1/analytics/usage/limits/org_abc123",
  {
    headers: {
      "X-API-Key": process.env.FREDDY_API_KEY
    }
  }
);

const data = await response.json();
console.log(`Organization status: ${data.organization_limits.status}`);
console.log(`Current usage: CHF ${data.organization_limits.current_usage}`);
```

**Response:**

200 OK

```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_abc123",
      "api_key_name": "Production Key",
      "monthly_limit": 5000.00,
      "current_usage": 4500.00,
      "utilization_percentage": 90.00,
      "status": "warning"
    },
    {
      "api_key_id": "apikey_def456",
      "api_key_name": "Development Key",
      "monthly_limit": 2000.00,
      "current_usage": 1750.50,
      "utilization_percentage": 87.53,
      "status": "warning"
    },
    {
      "api_key_id": "apikey_ghi789",
      "api_key_name": "Test Key",
      "monthly_limit": null,
      "current_usage": 0.00,
      "utilization_percentage": null,
      "status": "no_limit"
    }
  ],
  "summary": {
    "total_keys": 3,
    "keys_with_limits": 2,
    "keys_exceeded": 0,
    "overall_status": "warning"
  }
}
```

404 Not Found

```json
{
  "success": false,
  "error": {
    "code": "ORGANIZATION_NOT_FOUND",
    "message": "Organization not found",
    "system_message": "Organization not found",
    "type": "client_error",
    "status": 404,
    "details": {
      "organization_id": "org_123"
    },
    "trace_id": "abc-123-def",
    "timestamp": "2025-11-19T10:30:00Z"
  }
}
```

403 Forbidden

```json
{
  "success": false,
  "error": {
    "code": "ORGANIZATION_ACCESS_DENIED",
    "message": "You don't have permission to access this organization",
    "system_message": "Organization access denied",
    "type": "client_error",
    "status": 403,
    "details": {
      "organization_id": "org_123"
    },
    "trace_id": "def-456-ghi",
    "timestamp": "2025-11-19T10:30:00Z"
  }
}
```

422 Unprocessable Entity

```json
{
  "success": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid month or year",
    "system_message": "Validation error",
    "type": "client_error",
    "status": 422,
    "details": {
      "field": "month",
      "value": 13
    },
    "trace_id": "ghi-789-jkl",
    "timestamp": "2025-11-19T10:30:00Z"
  }
}
```

**Response:**

200 OK

```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_abc123",
      "api_key_name": "Production Key",
      "monthly_limit": 5000.00,
      "current_usage": 4500.00,
      "utilization_percentage": 90.00,
      "status": "warning"
    },
    {
      "api_key_id": "apikey_def456",
      "api_key_name": "Development Key",
      "monthly_limit": 2000.00,
      "current_usage": 1750.50,
      "utilization_percentage": 87.53,
      "status": "warning"
    },
    {
      "api_key_id": "apikey_ghi789",
      "api_key_name": "Test Key",
      "monthly_limit": null,
      "current_usage": 0.00,
      "utilization_percentage": null,
      "status": "no_limit"
    }
  ],
  "summary": {
    "total_keys": 3,
    "keys_with_limits": 2,
    "keys_exceeded": 0,
    "overall_status": "warning"
  }
}
```

404 Not Found

```json
{
  "success": false,
  "error": {
    "code": "ORGANIZATION_NOT_FOUND",
    "message": "Organization not found",
    "system_message": "Organization not found",
    "type": "client_error",
    "status": 404,
    "details": {
      "organization_id": "org_123"
    },
    "trace_id": "abc-123-def",
    "timestamp": "2025-11-19T10:30:00Z"
  }
}
```

403 Forbidden

```json
{
  "success": false,
  "error": {
    "code": "ORGANIZATION_ACCESS_DENIED",
    "message": "You don't have permission to access this organization",
    "system_message": "Organization access denied",
    "type": "client_error",
    "status": 403,
    "details": {
      "organization_id": "org_123"
    },
    "trace_id": "def-456-ghi",
    "timestamp": "2025-11-19T10:30:00Z"
  }
}
```

422 Unprocessable Entity

```json
{
  "success": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Invalid month or year",
    "system_message": "Validation error",
    "type": "client_error",
    "status": 422,
    "details": {
      "field": "month",
      "value": 13
    },
    "trace_id": "ghi-789-jkl",
    "timestamp": "2025-11-19T10:30:00Z"
  }
}
```