> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boltroute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Credit usage by API key

> Retrieve daily credit usage grouped by API key, including unknown attribution rows.

## 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:

```bash theme={null}
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:

```json theme={null}
{
  "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.