## Overview

The Get API Key Usage endpoint allows you to retrieve detailed billing and usage analytics for a specific API key over a given time period. This endpoint returns cost data from Exa’s billing system, providing an authoritative view of what you’re being billed for that API key.

## Path Parameters

- **id**: The unique identifier of the API key to retrieve usage for

## Query Parameters

- **start_date** (optional): Start date for the usage period in ISO 8601 format (e.g., `2025-01-01T00:00:00Z` or `2025-01-01`). Defaults to 30 days ago. Must be within the last 6 months (180 days).
- **end_date** (optional): End date for the usage period in ISO 8601 format. Defaults to the current time.
- **group_by** (optional): Time granularity for grouping results (`hour`, `day`, or `month`). Currently reserved for future enhancements and does not change the response shape. Defaults to `day`.

## Response

Returns detailed usage and billing information including:

- **api_key_id**: Unique identifier of the API key
- **api_key_name**: Descriptive name of the API key (if set)
- **team_id**: Team ID this key belongs to
- **period**: Object containing the start and end dates of the usage period
- **total_cost_usd**: Total cost in USD for the specified period
- **cost_breakdown**: Array of cost breakdowns by price type, each containing:
  - **price_id**: Unique identifier for the price
  - **price_name**: Name of the price (e.g., “Neural Search”, “Content Retrieval”)
  - **quantity**: Total quantity consumed
  - **amount_usd**: Cost in USD for this price type
- **metadata**: Object containing report generation timestamp

```json
{
  "api_key_id": "550e8400-e29b-41d4-a716-446655440000",
  "api_key_name": "Production API Key",
  "team_id": "660e8400-e29b-41d4-a716-446655440000",
  "period": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-01-31T23:59:59Z"
  },
  "total_cost_usd": 45.67,
  "cost_breakdown": [
    {
      "price_id": "price_neural_search",
      "price_name": "Neural Search",
      "quantity": 1000,
      "amount_usd": 30
    },
    {
      "price_id": "price_content_retrieval",
      "price_name": "Content Retrieval",
      "quantity": 500,
      "amount_usd": 15.67
    }
  ],
  "metadata": {
    "generated_at": "2025-02-01T10:30:00Z"
  }
}
```

## Important Notes

- **6-Month Lookback Limit**: The billing system has a 6-month (180-day) lookback limit. Requests with `start_date` older than 180 days will return a 400 error.
- **Zero Usage**: If the API key has no usage in the requested period, `total_cost_usd` will be 0 and `cost_breakdown` may be empty.
- **Team Ownership**: The service API key used for authentication must belong to the same team as the requested API key. Cross-team access is not permitted.
- **Date Formats**: Dates can be provided in ISO 8601 format with or without time components (e.g., `2025-01-01` or `2025-01-01T00:00:00Z`).

## Use Cases

This endpoint is useful for:

- Building API-key-level billing dashboards
- Monitoring usage and costs for specific API keys
- Creating automated alerts based on usage thresholds
- Generating usage reports for internal cost allocation
- Debugging billing questions for specific API keys

### Authorizations

**x-api-key**  
string  
header  
required  
Service API key for team authentication.