Skip to main content

​
AI usage breakdown

When your AI agents handle conversations, every LLM call they make is metered and priced. The Billing → Usage → AI page answers the question the overall usage total cannot: which agent, which model, and which channel burned the LLM budget — and how much of that spend prompt caching avoided. This guide covers the full loop:
  1. What the AI-split view aggregates.
  2. Per-agent, per-model, and per-cost-center (channel) columns.
  3. Disaggregating a spike by token class and cache-hit ratio.
  4. Time-window filters and export.
  5. How this page relates to the overall usage view and agent cost controls.
  6. A walkthrough of the screen, top to bottom.

​
1. What the AI-split view aggregates

Open Billing → Usage → AI from the dashboard. The page rolls up your AI agent usage on three axes — agent, model, and channel — over the window you pick. Every row reports:
  • Tokens — the sum of input and output tokens the aggregation axis consumed, plus cache-read and cache-creation tokens where the provider supports prompt caching.
  • Cost — the tenant-billed USD figure for the same tokens, computed from the per-model rate card. AI usage is priced at measured underlying cost plus a markup, and the headline figure is the billed (post-markup) amount. The summary strip shows the underlying, pre-markup cost directly underneath so you can always see what drives the bill.
  • Cache hit — the share of input tokens served from the provider’s prompt cache instead of being re-processed at full price.
A summary strip at the top totals the window: AI spend (with the pre-markup figure beneath it), total tokens, and cost per conversation alongside the conversation count. All amounts on this page are USD. LLM wholesale pricing is dollar-denominated, so the attribution is rendered in dollars regardless of your wallet currency — per-conversation and per-token-class figures use extended precision, since those amounts are often a fraction of a cent. Watch the billed figure rather than the wallet conversion when you reconcile against your invoice. Access follows the billing gate: the page is available to the owner, admin, and billing roles — the same roles that can open the parent usage drill-down.

​
2. Per-agent, per-model, and per-channel columns

Three sortable tables carry the attribution. Each opens sorted by cost descending — the row that matters in a spike is on top — and every column header re-sorts on click. By agent — one row per AI agent that handled traffic in the window: Use this table to answer “which agent doubled my bill” before anything else — then fix the prompt, the model, or the cost caps on that one agent. By model — the same tokens and cost grouped by the underlying LLM model your agents resolved to. Because model rates differ by an order of magnitude, this view is where you confirm a cheaper model swap actually moved money, or where a model preset change sent traffic to a more expensive class. By channel — the same spend grouped by the channel the agent replied on (sms, whatsapp, voice, email, …). If you treat channels as cost centers internally, this is your per-cost-center cut of the AI bill; for a department-first rollup of the messaging spend itself, see Cost-center chargeback.

​
3. Disaggregating a spike: token class annotations and cache ROI

The tables rank the suspects; the annotations tell you why a row is expensive. Token usage splits into four classes, and the split is attached to every aggregation row, not just the period total:
  • Input — tokens sent to the model (prompt, system instructions, retrieved context).
  • Output — tokens the model generated.
  • Cache read — input tokens served from the provider’s prompt cache at the discounted cache-read rate instead of the full input rate.
  • Cache creation — tokens spent writing a new cache entry.
On providers that support prompt caching, a high cache-hit ratio is real money: cached input is billed well below the full input rate. When a row’s cost is high but its cache hit is low, the annotation string is usually a long static prompt or a large retrieved context being re-sent on every turn — restabilising the prompt prefix (the cacheable part) is the cheapest fix. When cost is high and cache hit is high, look at output volume instead: cache never discounts the tokens the model writes. Cost per conversation is the other first-class annotation. A row with average cost but very high cost per conversation points at long agent loops — many LLM iterations per user turn — not at an expensive model. That is a prompt/tooling problem, addressed with the agent’s run and iteration limits (see Agent cost controls). If you need the class-level USD numbers rather than ratios, the API returns them per row as well as in a period-level cost_breakdown — see the export section below.

​
4. Time-window filters and export

The window chips at the top of the page pick a rolling window ending now:
  • 24h — today, for spotting a live spike.
  • 7d — the week, for trend checks.
  • 30d — the default; the month-scale view most reconciliation work starts from.
The chips are shortcuts over the same /usage/ai API the dashboard reads — so a script can pull exactly what the screen shows, including ranges the UI does not offer:
The response returns the period totals, the four-class token and cost breakdowns, the efficiency metrics (cache-hit ratio, cache savings, cost per conversation), and the three breakdown arrays GET /api/v1/usage/ai surfaces on the page — so the API doubles as your export path. Feed the JSON into your BI tool or convert it to CSV with any tool of choice for the month-end packet; for the wallet-wide statement export that covers all channels, see Cost-center chargeback §6. Usage rows stream into the ledger asynchronously. Figures on this page are settled attribution, but the current window keeps filling until it closes — compare like-for-like windows when you trend.

​
5. How this page relates to usage, cost controls, and the ledger

  • Billing → Usage is the overall view: wallet spend across every channel. The AI breakdown is the drill-down that splits the AI line of that aggregate by agent, model, and channel — the two surfaces reconcile over the same window.
  • Agent cost controls are the prevention side: per-run and per-conversation dollar caps and tool-iteration limits set on each agent. The usage breakdown is the detection side that tells you which agent needs a tighter cap or a cheaper model preset.
  • The figures are attribution over your metered LLM usage, not invoice math — they exclude subscription fees, credits, and tax, same discipline as the chargeback rollup.
  • For the underlying model of how token counts become dollars (rate-card resolution and the markup), see the LLM spend cost-attribution concept.

​
6. Screenshot sequence — the screen, top to bottom

Annotating the page panel by panel, in the order it renders:
  1. Header and window chips. The back link returns to Billing → Usage; the chips switch the rolling window.
  2. Summary strip. Three totals for the window: AI spend with the underlying pre-markup cost beneath it, total tokens, and cost per conversation with the conversation count under it.
  3. By agent. One row per agent, sorted by cost. Empty when no agent ran in the window.
  4. By model. One row per resolved model.
  5. By channel. One row per reply channel.
Empty states are per-table: a month with traffic on agents but none on, say, voice shows the agent table populated and the channel table with only its non-empty channels. Rows that cannot be tied to an agent, model, or channel show as unattributed rather than being dropped, so the tables always reconcile to the summary totals.