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

# Usage & Cost (v1)

> Read AI Gateway request counts, token counts, and estimated cost, grouped by model, over the public /v1 Management API.

# Usage & cost

Returns aggregated AI Gateway usage — request counts, input/output token counts, and estimated USD cost — broken down by provider and model, with tenant-wide totals. See the [control-plane overview](/api-reference/ai-gateway/control-plane-overview) for authentication and the response envelope.

## Get usage

```http theme={"dark"}
GET /v1/ai-gateway/usage
```

Requires the `read` capability on `ai_gateway`.

**Query parameters**

| Parameter  | Type                   | Description                                                               |
| ---------- | ---------------------- | ------------------------------------------------------------------------- |
| `period`   | `7d` \| `30d` \| `90d` | Look-back window. Defaults to `30d`; any other value is treated as `30d`. |
| `agent_id` | string (uuid)          | Optional. Restrict the aggregation to a single agent.                     |

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl "https://api.knoxcall.com/v1/ai-gateway/usage?period=30d" \
    -H "Authorization: Bearer tk_live_abc123..."
  ```

  ```python Python theme={"dark"}
  import requests

  resp = requests.get(
      "https://api.knoxcall.com/v1/ai-gateway/usage",
      headers={"Authorization": "Bearer tk_live_abc123..."},
      params={"period": "30d"},
  )
  usage = resp.json()["data"]
  ```

  ```javascript Node.js theme={"dark"}
  const resp = await fetch(
    "https://api.knoxcall.com/v1/ai-gateway/usage?period=30d",
    { headers: { Authorization: "Bearer tk_live_abc123..." } }
  );
  const { data: usage } = await resp.json();
  ```
</CodeGroup>

**Response**

```json theme={"dark"}
{
  "data": {
    "period_days": 30,
    "by_model": [
      {
        "provider": "anthropic",
        "model": "claude-sonnet-4-6",
        "requests": 1420,
        "input_tokens": 3120544,
        "output_tokens": 512310,
        "cost_usd": 42.87,
        "unpriced_requests": 0
      },
      {
        "provider": "openai",
        "model": "gpt-4o",
        "requests": 260,
        "input_tokens": 410233,
        "output_tokens": 88110,
        "cost_usd": 6.12,
        "unpriced_requests": 4
      }
    ],
    "totals": {
      "requests": 1680,
      "input_tokens": 3530777,
      "output_tokens": 600420,
      "cost_usd": 48.99,
      "unpriced_requests": 4
    }
  },
  "meta": {
    "request_id": "0d5b2a9e-1f3c-4a7d-8e2b-6c9a1f4d7e35"
  }
}
```

**Fields**

| Field                                       | Description                                                                                                       |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `period_days`                               | The resolved look-back window in days (`7`, `30`, or `90`).                                                       |
| `by_model[]`                                | One row per `(provider, model)` seen in the window, ordered by descending cost.                                   |
| `by_model[].requests`                       | Number of proxied requests.                                                                                       |
| `by_model[].input_tokens` / `output_tokens` | Summed token counts.                                                                                              |
| `by_model[].cost_usd`                       | Estimated cost in USD.                                                                                            |
| `by_model[].unpriced_requests`              | Requests for which no price could be computed (model not in the price table); these contribute `0` to `cost_usd`. |
| `totals`                                    | The same metrics summed across every `by_model` row.                                                              |

<Note>
  `cost_usd` is an estimate derived from KnoxCall's model price table. When `unpriced_requests` is non-zero, the true cost for those requests is higher than the reported `cost_usd`.
</Note>