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

# Get API Key Usage

> Calls, success rate, latency, spend and top tools for one API key over a window of days

## Overview

Returns what one API key did over the last `days` days: how many tool calls it made, how many succeeded, its median latency, how much it spent, and the ten tools it called most. Each key is one agent's identity in Danube, so this is the per-agent usage view.

Only tool executions stamped with this key are counted. Synthetic probe calls are excluded.

**Auth:** Requires authentication (JWT or API key). The key must belong to the caller.

## Path Parameters

<ParamField path="key_id" type="string" required>
  The API key UUID: the `id` from [List API Keys](/api-reference/endpoint/list_api_keys), not the key value
</ParamField>

## Query Parameters

<ParamField query="days" type="integer" default="30">
  Length of the window in days. Clamped to 1 through 90.
</ParamField>

## Response

<ResponseField name="key" type="object">
  <Expandable title="Key">
    <ResponseField name="id" type="string">API key UUID</ResponseField>
    <ResponseField name="name" type="string">Display name for the key</ResponseField>
    <ResponseField name="agent_name" type="string | null">The agent this key identifies</ResponseField>
    <ResponseField name="agent_type" type="string | null">`coding_agent`, `assistant`, `workflow`, `service` or `other`</ResponseField>
    <ResponseField name="purpose" type="string | null">What the key is for</ResponseField>
    <ResponseField name="created_at" type="string">ISO 8601 creation timestamp</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="window_days" type="integer">The window used, after clamping</ResponseField>
<ResponseField name="calls" type="integer">Tool calls in the window</ResponseField>
<ResponseField name="successes" type="integer">Calls with status `success`</ResponseField>
<ResponseField name="success_rate" type="number | null">`successes / calls`, rounded to four decimals. `null` when there were no calls.</ResponseField>
<ResponseField name="p50_seconds" type="number | null">Median execution time of successful calls, in seconds, rounded to three decimals. `null` when there were none.</ResponseField>
<ResponseField name="paid_calls" type="integer">Calls that cost more than zero cents</ResponseField>
<ResponseField name="spent_cents" type="integer">Total cost of the calls in the window, in cents</ResponseField>
<ResponseField name="first_call_at" type="string | null">Earliest call in the window (ISO 8601). `null` when there were no calls.</ResponseField>
<ResponseField name="last_call_at" type="string | null">Latest call in the window (ISO 8601). `null` when there were no calls.</ResponseField>

<ResponseField name="top_tools" type="array">
  Up to ten tools, most called first.

  <Expandable title="Tool entry">
    <ResponseField name="tool_id" type="string">Tool UUID</ResponseField>
    <ResponseField name="tool_name" type="string">Tool name</ResponseField>
    <ResponseField name="service_name" type="string">Service name</ResponseField>
    <ResponseField name="calls" type="integer">Calls to this tool in the window</ResponseField>
    <ResponseField name="successes" type="integer">Successful calls to this tool</ResponseField>
  </Expandable>
</ResponseField>

## Errors

| Code | Meaning                                       |
| ---- | --------------------------------------------- |
| 401  | Missing or invalid auth                       |
| 404  | No API key with this id belongs to the caller |
| 503  | Usage is temporarily unavailable              |

## Example

The Python and TypeScript SDKs do not wrap this endpoint yet.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.danubeai.com/v1/api-keys/KEY_ID/usage?days=7" \
    -H "danube-api-key: YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "key": {
      "id": "0b6a2c1e-9f4d-4e3a-b7c8-5d6e7f8a9b0c",
      "name": "research-bot",
      "agent_name": "research-bot",
      "agent_type": "coding_agent",
      "purpose": "Nightly literature sweep",
      "created_at": "2026-08-20T10:00:00+00:00"
    },
    "window_days": 7,
    "calls": 148,
    "successes": 141,
    "success_rate": 0.9527,
    "p50_seconds": 0.842,
    "paid_calls": 12,
    "spent_cents": 36,
    "first_call_at": "2026-09-05T02:10:11.482+00:00",
    "last_call_at": "2026-09-11T23:58:40.017+00:00",
    "top_tools": [
      {
        "tool_id": "8ca97ef7-acf5-4869-b043-a9960a9f8085",
        "tool_name": "Hacker News - Get Top Stories With Content",
        "service_name": "Hacker News",
        "calls": 96,
        "successes": 96
      }
    ]
  }
  ```
</ResponseExample>