Operations
Usage API

Usage API

Programmatically retrieve your account's usage and cost data.

Endpoint

  • Method: GET
  • URL: /api/v1/usage
  • Auth: Authorization: Bearer $API_KEY
  • Content-Type: application/json

Query parameters

  • timeframe (string, optional)
    • One of: 24h, 7d, 30d
    • Default: 24h
  • from (ISO datetime, optional)
  • to (ISO datetime, optional)
  • granularity (string, optional)
    • One of: hour, day
    • Default: day for 7d/30d, hour for 24h
  • model (string, optional)
    • Filter by model id (e.g., gpt-5-mini-2025-08-07, claude-sonnet-4-5-20250929)

Note: When both timeframe and from/to are supplied, from/to take precedence.

Response schema

{
  "totals": {
    "total_requests": 1234,
    "total_tokens": 456789,
    "input_tokens": 300000,
    "output_tokens": 156789,
    "total_cost": 1.2345
  },
  "series": [
    {
      "timestamp": "2025-11-06T12:00:00.000Z",
      "requests": 120,
      "input_tokens": 11000,
      "output_tokens": 3200,
      "cost": 0.0321
    }
  ],
  "top_models": [
    {
      "model": "gpt-5-mini-2025-08-07",
      "requests": 800,
      "tokens": 320000,
      "cost": 0.8888
    }
  ]
}

Field notes:

  • totals.total_cost reflects discounted pricing as applied by KushRouter (see pricing).
  • series granularity depends on the granularity parameter.
  • top_models summarizes usage by model across the window.

Examples

cURL

curl -X GET "https://api.kushrouter.com/api/v1/usage?timeframe=7d&granularity=day" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json"

JavaScript

const res = await fetch('https://api.kushrouter.com/api/v1/usage?timeframe=24h&granularity=hour', {
  headers: {
    Authorization: `Bearer ${process.env.KUSHROUTER_API_KEY}`,
  },
});
const usage = await res.json();
console.log('Total requests:', usage.totals.total_requests);

SDK (if using the KushRouter SDK)

const usage = await sdk.getUsage({ timeframe: '7d', granularity: 'day' });
console.log(usage.totals.total_cost);

Error handling

  • 401 — invalid/missing key
  • 429 — rate-limited; retry with exponential backoff
  • 500 — transient error; capture x-request-id in response headers for support

See also

Usage analyticsRate limits