Skip to main content

​
Overview

Retrieve usage details for a specific API key, including optional daily series when a date range is provided.

​
GET /api/v1/api-keys//usage

Purpose: return usage data for a single API key. Path parameter:
  • id (UUID)
Query parameters:
  • from (RFC3339 timestamp, optional): include daily usage from this timestamp (used for time series). Defaults to key created_at when only to is provided.
  • to (RFC3339 timestamp, optional): include daily usage up to this timestamp (used for time series). Defaults to now when only from is provided.
Notes:
  • Series data is included when either from or to is provided.
  • If to is missing, it defaults to now; if from is missing, it defaults to the API key created_at. The computed bounds are normalized via normalizeToUTCDate.
  • Daily buckets come from buildDailySeriesDates, and the series is generated via c.buildAPIKeyUsageSeries using the computed start/end.
Example request: 
curl -X GET \
  'https://api.example.com/api/v1/api-keys/550e8400-e29b-41d4-a716-446655440000/usage?from=2025-01-01T00:00:00Z&to=2025-01-07T00:00:00Z'

​
Response

Status: 200 OK Example response: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Production Key",
  "purpose": "zapier",
  "usage_count": 1234,
  "last_used_at": "2025-01-07T12:00:00Z",
  "created_at": "2025-01-01T12:00:00Z",
  "is_active": true,
  "series": [
    { "date": "2025-01-01", "usage_count": 120 },
    { "date": "2025-01-02", "usage_count": 98 }
  ]
}
Errors:
  • 400 invalid UUID.
  • 401 unauthorized.
  • 404 key not found.
  • 500 internal error.