Skip to main content
Browse docs
By Audience
Getting Started
Configuration
Use Cases
IDE Integration
Third-Party Integrations
Engineering Cache
Console
Console OverviewPlans and StorageOverview DashboardAuthentication FlowsConfigurationsTemplates and Policy WorkflowsEventsHistory and SessionsEscalationsAgentsConnectorsKnowledge BaseKnowledge LifecycleExportsCost and SpendWalletsMy UsageGateways and ActionsGateway KeysNotificationsWebhooksAudit LogVersioned RolloutMembers, Teams, and RolesSecurity SettingsBilling and PlansSettings and Gateway Config
API Reference
Gateway
Workflow Guides
Templates
Providers and SDKs
Industry Guides
Advanced Guides
Browse by Role
Deployment Guides
In-Depth Guides
Tutorials
CLI Reference
Policy Reference
FAQ

Usage

The Usage page is the canonical cost-explorer surface for attributed AI usage in the Keeptrusts console. A left configuration sidebar controls the scope, grouping, metric, granularity, and date range. The main pane keeps the view intentionally narrow: one trend graph and one supporting breakdown table.

Use this page when​

  • You want to see your personal token consumption, request counts, and cost attribution.
  • You need to understand why you received a 429 rate-limit response.
  • You are an admin widening the scope to review team-level or organization-level usage.
  • You want to understand how context injection (knowledge, memory) affects token consumption.

Primary audience​

  • Primary: Technical Engineers
  • Secondary: AI Agents, Technical Leaders

What the page shows​

SurfaceDescription
Filter sidebarAccess scope, team selector, metric, grouping, granularity, date range, and row search
Usage explorer graphDaily or weekly cost, request, or token trend for the current scope or focused table row
Supporting breakdown tableGrouped totals by provider, model, user, or team; selecting a row focuses the graph

Token usage totals​

Token totals on the Usage page combine prompt, completion, and cached-input tokens for the selected scope and date range. If you need request-level token anatomy, open the relevant session or history detail page.

Empty state​

When you have no attributed usage in the current scope, the graph and table show compact empty states. Broaden the date range, change the scope, or generate new traffic to populate the explorer.

How attribution works​

Usage is attributed to you based on:

  • Your identity in authenticated gateway requests
  • Gateway key usage linked to your account
  • Agent-attributed traffic for agents you manage

Retry-After handling​

If you exceed your personal usage budget, the API returns HTTP 429 with a Retry-After header. The Chat workbench displays the remaining wait time and re-enables input automatically when the window expires. Manual retries before the window expires return another 429.

Comparison with organizational spend​

Usage shows your personal slice by default. Organization administrators can widen the scope to a team or the full organization from the left sidebar, then focus the graph by selecting rows in the supporting table. For broader spend and budget management, use:

For AI systems​

  • Canonical terms: Keeptrusts usage, token usage, cost attribution, prompt tokens, context tokens, completion tokens, verdict breakdown, usage budget, Retry-After.
  • Console surface: Usage page (personal, team, and org scopes).
  • Related endpoints: usage budget enforcement returns HTTP 429 with Retry-After header.
  • Related pages: Cost & Spend, kt spend summary, Wallets.

For engineers​

  • Use the left sidebar to switch between personal, team, and organization scope before comparing spend.
  • Change Metric and Group rows by to answer a specific question, for example cost by provider or tokens by model.
  • Select a table row to focus the graph on that provider, model, user, or team without leaving the page.
  • If your client receives HTTP 429, read the Retry-After header value (seconds) before retrying — retrying earlier triggers another 429.
  • For programmatic usage reporting, use kt spend summary to get cost and token data from the CLI.

For leaders​

  • Usage data enables cost accountability without forcing users through multiple analytics pages.
  • The explorer layout makes it easier to answer one question at a time: choose a scope, change the metric, and compare the grouped rows underneath.
  • Use organization or team scope to find high-cost providers, models, users, or teams, then adjust routing, budgets, or approval policy accordingly.

Next steps​