# Get top API usage

div
strong
🔨 In Development
 — This section is still being developed and may change.


Identify the highest-cost API keys for an organization within a billing period, including per-period breakdowns.

#### Path Parameters

**`orgId`** string required

Unique organization identifier (format: `ORG_` + 16 chars).

**`month`** integer required

Target billing month (1-12).

**`year`** integer required

Target billing year (e.g., `2025`).

#### Query Parameters

**`limit`** integer optional · Defaults to `10`, max `50`

Maximum number of API keys to return.

**`period`** string optional · Defaults to `daily`

Aggregation granularity. One of: `daily`, `weekly`, `monthly`.

#### Authentication

- `Authorization: Bearer $FREDDY_API_KEY`


## Returns

Top API keys ordered by total spend, with per-period consumption metrics and summary totals.

Request

```bash
curl "https://api.freddy.aitronos.com/v1/analytics/ORG_B66136CBB1304C98/api-keys/top/10/2025?limit=3&period=daily" \
-H "Authorization: Bearer $FREDDY_API_KEY"
```


```python
import requests

response = requests.get(
    "https://api.freddy.aitronos.com/v1/analytics/ORG_B66136CBB1304C98/api-keys/top/10/2025",
    headers={"Authorization": f"Bearer {api_key}"},
    params={"limit": 3, "period": "daily"}
)

top_keys = response.json()["topApiKeys"]
for item in top_keys:
    print(item["apiKeyName"], item["totalCost"])
```

## Response

200 OK

```json
{
  "organizationId": "ORG_B66136CBB1304C98",
  "period": {
    "month": 10,
    "year": 2025
  },
  "topApiKeys": [
    {
      "apiKeyId": "ak_5daf103fe74c8603",
      "apiKeyName": "Production API Key",
      "totalCost": 1250.45,
      "totalRequests": 8923,
      "dailyUsage": [
        {
          "date": "2025-10-15",
          "cost": 45.67,
          "requests": 234
        },
        {
          "date": "2025-10-16",
          "cost": 52.89,
          "requests": 267
        }
      ]
    }
  ],
  "summary": {
    "totalApiKeys": 3,
    "totalCost": 3589.23,
    "totalRequests": 25678,
    "averageCostPerRequest": 0.14
  },
  "breakdownType": "daily"
}
```

Errors
**400 Bad Request**


```json
{
  "error": {
    "message": "Limit must be between 1 and 50",
    "type": "validation_error",
    "code": "invalid_limit"
  }
}
```

**401 Unauthorized**


```json
{
  "error": {
    "message": "Authentication required",
    "type": "authentication_error",
    "code": "missing_authentication"
  }
}
```

## Related Resources

- [Get organization usage limits](/docs/api-reference/organizations/analytics/get-usage-limit)
- [Get API key usage](/docs/api-reference/organizations/analytics/get-api-key-usage)