---
title: "Get per-API-key usage"
method: GET
path: "/api/v1/me/api-keys/{id}/usage"
tags: ["Settings"]
---

# Get per-API-key usage

`GET /api/v1/me/api-keys/{id}/usage`

## Request

- Base URL: `https://api.proof.holdings`
- URL: `https://api.proof.holdings/api/v1/me/api-keys/{id}/usage`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `auth_token`

Per-API-key usage: verification counts by type/channel/status plus per-collection totals (requests, confirmations, authorizations) and attribution metadata. The counts cover the key and every key it replaced (`api_key.replaced_key_ids`). Counts only — no recipient identifiers (SEC-001). Resolves across both key collections, scoped to the requesting user (IDOR); data is returned for revoked keys (audit). An API-key caller may read only its own key usage. (h-dashboard-per-key-api)

## Path parameters

- `id` string, required: API key id (UserAPIKey or legacy APIKey)

## Query parameters

- `environment` 'production' | 'test': Scope metrics to test or production (default: the calling key environment)

## Response `200`

Per-key usage counts + attribution

- ApiKeyUsageResponse: Per-API-key usage: verification counts by type/channel/status + per-collection totals (requests, confirmations, authorizations) + attribution metadata. The counts cover the key and every key it replaced (`api_key.replaced_key_ids`). Counts only — no recipient identifiers (SEC-001). Data is returned for revoked keys (audit).
  - `api_key` object, required
    - `id` string, required: MongoDB ObjectId
    - `name` string, required
    - `key_prefix` string, required
    - `environment` string, required
    - `scopes` string[], required
    - `profile_id` string: MongoDB ObjectId
    - `last_used_at` string, date-time, nullable, required
    - `expires_at` string, date-time, nullable, required: When the key stops authenticating; null means it never expires
    - `revoked_at` string, date-time, nullable, required
    - `replaced_key_ids` ObjectId[]: Ids of the keys this key replaced, newest first: the earlier keys of the same integration, replaced when the key was regenerated (`POST /api/v1/me/api-keys/{id}/regenerate`) or renewed by an MCP sign-in refresh. Requests and usage of those keys count as this key's. Empty when it replaced none. Recorded from the release of key history on; a key replaced before it is not linked.
    - `created_at` string, date-time, required
  - `verifications` object, required
    - `total` number, required
    - `by_type` object, required
    - `by_channel` object, required
    - `by_status` object, required
  - `verification_requests` object, required
    - `total` number, required
    - `by_status` object, required
  - `confirmations` object, required
    - `total` number, required
    - `by_status` object, required
  - `authorizations` object, required
    - `total` number, required
    - `by_status` object, required
  - `attribution_cutoff_at` string, date-time, nullable, required: UTC-day-floored date attribution began for this user (earliest key-linked verification), or null
  - `attributed_fraction` number, nullable, required: Fraction of the user verifications linked to any API key in scope (null when there are none)

## Other responses

- `401`: Unauthorized
- `403`: An API key may only read its own usage
- `404`: API key not found

---

[API](https://skmtc.dev/proof/apis/proof-holdings-api.md) · [All operations](https://skmtc.dev/proof/apis/proof-holdings-api/llms.txt) · [OpenAPI document](https://skmtc.dev/proof/apis/proof-holdings-api/revisions/b15f506de696?raw)