Skip to main content
GET
/
api-keys
/
{id}
/
usage
curl -X GET 'https://admin-api.exa.ai/team-management/api-keys/{id}/usage' \
  -H 'x-api-key: YOUR-SERVICE-KEY'
{
  "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"
  }
}

Get your Exa API key

​
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 100 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

​
Important Notes

  • 100-Day Lookback Limit: The billing system has a 100-day lookback limit. Requests with start_date older than 100 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

Path Parameters

​
id
string<uuid>
required

The unique identifier of the API key

Query Parameters

​
start_date
string<date-time>

Start date for the usage period (ISO 8601 format). Defaults to 30 days ago. Must be within the last 100 days.

​
end_date
string<date-time>

End date for the usage period (ISO 8601 format). Defaults to current time.

​
group_by
enum<string>

Time granularity for grouping results. Currently reserved for future enhancements and does not change the response shape. Defaults to 'day'.

Available options:
hour,
day,
month

Response

Usage data retrieved successfully

​
api_key_id
string<uuid>

The API key ID

​
api_key_name
string | null

The name of the API key

​
team_id
string<uuid>

The team ID this key belongs to

​
period
object
​
total_cost_usd
number

Total cost in USD for the period

Example:

45.67

​
cost_breakdown
object[]

Breakdown of costs by price type

​
metadata
object