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 for authentication and the response envelope.

Get usage

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.

curl "https://api.knoxcall.com/v1/ai-gateway/usage?period=30d" \
  -H "Authorization: Bearer tk_live_abc123..."

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"]

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();

Response

{
  "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.

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.