> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# AI usage breakdown: attribute LLM spend per agent, model, and channel

> Open Billing → Usage → AI to see token in/out and cost split per agent, per model, and per channel — with prompt-cache ROI on every row — and export the same attribution through the usage API.

# 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:

| Column      | Meaning                                                                    |
| ----------- | -------------------------------------------------------------------------- |
| Agent       | The agent identifier. Runs not tied to an agent land under *unattributed*. |
| Convs       | Conversations the agent touched in the window.                             |
| Tokens      | Input + output tokens for the agent's runs.                                |
| Cost        | Billed USD for those tokens.                                               |
| Cost / conv | The agent's cost divided by its conversation count.                        |
| Cache hit   | Share of input tokens served from prompt cache.                            |

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](/guides/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](/agents/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:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/usage/ai?window=30d" \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

| Query parameter | Notes                                                                                                     |
| --------------- | --------------------------------------------------------------------------------------------------------- |
| `window`        | Rolling shortcut: `24h`, `7d`, or `30d`. Takes precedence over the other selectors.                       |
| `from` + `to`   | Explicit ISO-8601 range (both required together) — use this for arbitrary windows the chips do not cover. |
| `period`        | Calendar month as `YYYY-MM`. Defaults to the current month when nothing is passed.                        |

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](/guides/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](/billing/overview)** 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](/agents/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](/concepts/llm-spend-cost-attribution-model).

***

## 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.