GET

ai-gateway

usage

Get AI gateway usage

curl --request GET \
  --url https://api.knoxcall.com/v1/ai-gateway/usage \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.knoxcall.com/v1/ai-gateway/usage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.knoxcall.com/v1/ai-gateway/usage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.knoxcall.com/v1/ai-gateway/usage"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.knoxcall.com/v1/ai-gateway/usage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": {
    "period_days": 123,
    "by_model": [
      {
        "provider": "<string>",
        "model": "<string>",
        "requests": 123,
        "input_tokens": 123,
        "output_tokens": 123,
        "cost_usd": 123,
        "unpriced_requests": 123
      }
    ],
    "totals": {
      "requests": 123,
      "input_tokens": 123,
      "output_tokens": 123,
      "cost_usd": 123,
      "unpriced_requests": 123
    }
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

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 — the examples below authenticate with $TOKEN, a short-lived OAuth 2.1 access token minted there.

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 $TOKEN"

import os
import requests

TOKEN = os.environ["KNOXCALL_ACCESS_TOKEN"]  # OAuth access token — see Authentication

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

const resp = await fetch(
  "https://api.knoxcall.com/v1/ai-gateway/usage?period=30d",
  { headers: { Authorization: `Bearer ${process.env.KNOXCALL_ACCESS_TOKEN}` } }
);
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.

Authorizations

Authorization

string

header

required

OAuth 2.1 authentication — recommended for new integrations. Access tokens (kc_ prefix) are minted at the root-host token endpoint https://api.knoxcall.com/oauth/token and passed as Authorization: Bearer <access_token>. Public clients must use PKCE with the authorization_code grant; confidential clients may use client_credentials. The first-party SDKs and the knoxcall login CLI handle token minting, caching, refresh, and DPoP for you.

Query Parameters

period

enum<string>

default:30d

The rollup window. Defaults to 30 days.

Available options:

7d,

30d,

90d

agent_id

string<uuid>

Scope the rollup to a single agent.

Response

The usage rollup.

data

object

Cost and token rollup by model over the requested period.

Show child attributes

meta

object

Metadata included with every API response.

Show child attributes

Get AI gateway usage

curl --request GET \
  --url https://api.knoxcall.com/v1/ai-gateway/usage \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.knoxcall.com/v1/ai-gateway/usage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.knoxcall.com/v1/ai-gateway/usage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.knoxcall.com/v1/ai-gateway/usage"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.knoxcall.com/v1/ai-gateway/usage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": {
    "period_days": 123,
    "by_model": [
      {
        "provider": "<string>",
        "model": "<string>",
        "requests": 123,
        "input_tokens": 123,
        "output_tokens": 123,
        "cost_usd": 123,
        "unpriced_requests": 123
      }
    ],
    "totals": {
      "requests": 123,
      "input_tokens": 123,
      "output_tokens": 123,
      "cost_usd": 123,
      "unpriced_requests": 123
    }
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Overview

Routes

Secrets

Clients

Environments

API Keys

Webhooks

Ephemeral Proxy

AI Gateway

Audit Logs

Account

Tenant KMS

Secret Store Migrations

Changelog

Usage & Cost (v1)

Usage & cost

Get usage

Authorizations

Query Parameters

Response

​Usage & cost

​Get usage

Authorizations

Query Parameters

Response

Usage & cost

Get usage