Skip to main content

​
Overview

Return daily credit usage grouped by API key for the authenticated user.

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

Purpose: return credit usage metrics grouped by API key. Query parameters:
  • from (RFC3339 timestamp, required): start timestamp for the series window.
  • to (RFC3339 timestamp, required): end timestamp for the series window.
  • api_key_id (UUID, optional): filter to a single API key.
Notes:
  • from and to must be provided together.
  • The date range is capped at 90 days.
  • The query includes credit rows where metadata.source = "api_key" and legacy rows where source is missing.
  • The query excludes rows where metadata.source = "frontend".
  • Records with missing or invalid metadata.api_key_id are grouped into an is_unknown = true bucket.
  • When an API key still exists, api_key_name, api_key_purpose, and is_active are populated from api_keys.
  • api_key_id returns only the matching API key bucket.
Example request: 
curl -X GET \
  'https://api.boltroute.ai/api/v1/credits/usage/api-keys?from=2025-01-01T00:00:00Z&to=2025-01-03T00:00:00Z' \
  -H 'Authorization: Bearer <api_key_or_jwt>'

​
Response

Status: 200 OK Example response: 
{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "from": "2025-01-01T00:00:00Z",
  "to": "2025-01-03T00:00:00Z",
  "keys": [
    {
      "api_key_id": "550e8400-e29b-41d4-a716-446655440000",
      "api_key_name": "Production key",
      "api_key_purpose": "zapier",
      "is_active": true,
      "is_unknown": false,
      "totals": { "used_credits": 10, "granted_credits": 5, "net_credits": 5 },
      "series": [
        { "date": "2025-01-01", "used_credits": 10, "granted_credits": 0, "net_credits": 10 },
        { "date": "2025-01-02", "used_credits": 0, "granted_credits": 5, "net_credits": -5 },
        { "date": "2025-01-03", "used_credits": 0, "granted_credits": 0, "net_credits": 0 }
      ]
    },
    {
      "is_unknown": true,
      "totals": { "used_credits": 3, "granted_credits": 0, "net_credits": 3 },
      "series": [
        { "date": "2025-01-01", "used_credits": 0, "granted_credits": 0, "net_credits": 0 },
        { "date": "2025-01-02", "used_credits": 0, "granted_credits": 0, "net_credits": 0 },
        { "date": "2025-01-03", "used_credits": 3, "granted_credits": 0, "net_credits": 3 }
      ]
    }
  ]
}
Errors:
  • 400 invalid date parameters, invalid api_key_id, or missing required range.
  • 401 unauthorized.
  • 500 internal error while computing usage.