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

{
  "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.