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

# Agent spend attribution

> What the fleet costs per run, agent, and model — how each figure is derived, and how to cap spend with budgets.

**Agent spend** answers what your agents cost, where the money went, and whether it is trending up.
The Komodor Agentic Operation Platform (KAOP) builds every figure from the usage each run reports, so
a total on this page can always be traced back to specific runs. This page explains where the numbers
come from, why some are reported and some estimated, and how to put a cap on an agent.

Find it under **Agents → Agent spend**, which carries three views: **Spend**, **Budgets**, and
**Opportunities**.

## What you see

Pick a window of **Last 7 days**, **Last 30 days**, or **Last 90 days** — 30 by default.

| Figure                      | What it reports                                                                                            |
| --------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Total spend**             | Attributed spend in the window, with its estimated and reported split.                                     |
| **vs previous period**      | The same figure against the preceding window of equal length.                                              |
| **Cost per successful run** | Total spend divided by runs that succeeded — the closest thing to a unit cost.                             |
| **Spend over time**         | A daily series, as a line or bars.                                                                         |
| **Spend breakdown**         | Attributed cost by dimension, each entry with its share of spend, its run count, and its cost per success. |
| **Most expensive runs**     | The top runs by attributed cost.                                                                           |

The breakdown can be pivoted by **Label**, **Agent**, **Model**, **Provider**, **MCP server**, or
**Tool**.

<Note>
  Cost also appears where you are already looking: the workspace **Overview** shows 30-day spend,
  [Fleet health](/manage-your-agents/optimize/fleet-health) shows window cost and cost per run per
  agent, Insights shows known cost and the per-model mix, and
  every run's detail shows its own usage.
</Note>

<Warning>
  Tool and MCP-server cost is attributed from the model step that triggered the call — step-level
  attribution — and is therefore **always shown as estimated**. A tool call does not price itself; what
  it costs is the model turn that decided to make it.
</Warning>

## Where the numbers come from

Every run carries a **usage** record: the provider, the model, the token breakdown, a cost amount, a
currency, and a cost source. The usage is merged from what the worker reports during the run — token
events, the run's output, and its metadata. Each run's cost then falls into one of three classes.

| Class            | How it is derived                                                                                                                                                                                                           |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Reported**     | The worker supplied a cost amount directly, from its own model client's accounting. A reported cost is authoritative and is never downgraded by a later estimate.                                                           |
| **Estimated**    | No reported cost, but the run named a model and carried token counts — so the control plane prices it from the model's published rates: input tokens, cached input, cache writes, and output tokens each at their own rate. |
| **Unattributed** | A cost amount exists but carries no source classification.                                                                                                                                                                  |

Runs with no usage record at all contribute runs but no cost.

<Info>
  **Why the split is shown rather than hidden.** A single "total spend" number silently mixes figures a
  provider billed you for with figures KAOP computed from token counts and published rates. Those have
  different error bars, and treating them as one is how a cost review ends in an argument. The split is
  on the tile so you always know how much of the total is measured and how much is modelled.
</Info>

### When a worker's own figure is discarded

If a run names a provider KAOP does not price directly and the model's rate is resolvable, the
worker's own cost figure is discarded and the cost is re-estimated from those rates. That is
deliberate: a worker-supplied figure for a provider the platform cannot corroborate is not more
trustworthy than a rate-based estimate, and mixing the two conventions within one total is worse than
either.

Where cache rates are not published for a model, they are derived from its input rate — cached reads
at a fraction of it, cache writes at a premium to it.

<Warning>
  If no rate can be resolved for a model at all, that run's cost is **left unset** rather than guessed.
  It shows up as runs with no cost, which is a data-quality signal about the model, not evidence that
  the work was free.
</Warning>

## Making your agents' cost show up

Agents built on the KAOP SDK adapters report token usage automatically. If you build a worker
yourself, include a usage object in the run's output or metadata. Several field aliases are accepted,
so most existing usage shapes work unchanged:

| Field         | Accepted keys                                                                        |
| ------------- | ------------------------------------------------------------------------------------ |
| Model         | `model`, `model_id`, `model_name`                                                    |
| Provider      | `provider`, `llm_provider`                                                           |
| Input tokens  | `input_tokens`, `prompt_tokens`, `prompt_token_count`, `input_token_count`           |
| Output tokens | `output_tokens`, `completion_tokens`, `completion_token_count`, `output_token_count` |
| Cost          | `cost_amount`, `cost`, `cost_usd`, `total_cost`, plus an optional `currency`         |

Report a cost amount to get **reported** cost. Report a model plus token counts to get an
**estimate**. Report neither and the run contributes volume but no spend.

<Tip>
  Reporting model and tokens is usually the better choice even when you could compute a cost yourself.
  It keeps one pricing convention across the fleet, so agent-to-agent comparisons on the breakdown are
  comparisons of usage rather than of two teams' accounting.
</Tip>

## Reading spend through the API

The **Spend** view is backed by the workspace activity endpoint, which you can call directly.

```bash theme={null}
# Workspace totals, daily buckets, per-agent summaries with model mix,
# and the top-cost runs for the window
GET /api/v1/runs/activity/workspace?window_days=30

# The same summary for a single agent
GET /api/v1/runs/activity/agents/{agent_id}?window_days=30
```

Both return run counts split into succeeded, failed, and active; cost totals split by source; daily
buckets; and the per-model mix. `window_days` accepts 1 to 365.

## Budgets

A budget caps what an agent may spend in a time window, and optionally stops it when the cap is
reached. Budgets are managed on the **Budgets** view and on an agent's own **Budgets** tab.

<Note>
  Budgets are enabled per workspace. If you do not see the view, ask your Komodor contact to turn it
  on — see [Support](/reference/support).
</Note>

### Setting one

<Steps>
  <Step title="Pick the windows">
    Under **Spend cap by window**, enable any combination of **Hourly**, **Daily**, **Weekly**, and
    **Monthly**, each with its own cap amount. Each window is an independent budget that resets on
    its own clock — hourly at the top of the hour, daily at midnight UTC, weekly on Monday, monthly
    on the first.
  </Step>

  <Step title="Set the notification threshold">
    A percentage of the cap. Crossing it is what makes the budget read **Near cap** rather than
    **OK**, before it is actually reached.
  </Step>

  <Step title="Choose what happens when the cap is hit">
    **Notify only** or **Block new runs**.
  </Step>
</Steps>

### What "Block new runs" does

The behavior is specific, and worth reading before you enable it:

* The agent's **schedule, webhook, and channel triggers stop firing** until the window resets. A run
  that was already queued is cancelled.
* A run **already in progress is terminated** when the cap is hit.
* **Manual invocation still works.** You can always run the agent yourself from the console.

<Warning>
  Blocking is the right default for a runaway-cost guard and the wrong default for anything on your
  critical path. A blocked agent stops responding to its triggers entirely, which for an
  incident-facing agent means it is absent exactly when it is needed. Start with **Notify only**, and
  move to blocking once you know the agent's normal spend shape.
</Warning>

### Reading the Budgets view

Three tiles summarize the picture: agents with a budget, the combined cap across all windows, and
how many budgets are at or near their cap. The table then lists each budget with its **Cap &
window**, **Spend this period**, **Status**, and **Resets in**.

| Status        | Meaning                                             |
| ------------- | --------------------------------------------------- |
| **OK**        | Below the notification threshold.                   |
| **Near cap**  | At or past the threshold, not yet at the cap.       |
| **Exhausted** | At or past the cap. Blocking budgets are enforcing. |

Spend against a budget counts finished runs, so a run still in flight is not yet charged against the
window — with one exception: the enforcement check for a blocking budget includes runs currently
executing, because a cap you can exceed by starting enough runs at once is not a cap.

<Note>
  A budget cannot be created for an agent that brings its own model key. KAOP does not see that
  agent's spend, so a cap it could neither measure nor enforce is refused rather than accepted and
  quietly ignored.
</Note>

## Bringing spend down

The **Opportunities** view lists spend inefficiencies KAOP has found across the fleet, alongside the
quality opportunities in
[Continuous Improvement](/manage-your-agents/optimize/continuous-improvement). The two share one
mechanism deliberately: a cheaper model that is also worse is not a saving, and the only way to know
is to settle the change as an experiment.

<Steps>
  <Step title="Find the concentration">
    Pivot the breakdown by **Agent**, then by **Model**. Spend is almost never evenly spread — one
    agent or one model usually dominates.
  </Step>

  <Step title="Read cost per success, not total">
    A high-volume agent with a low unit cost is working. A low-volume agent with a high unit cost is
    the one to look at.
  </Step>

  <Step title="Open the most expensive runs">
    Each one links to its evidence. An outlier run usually explains itself — a retry storm, an
    oversized context, or a tool loop.
  </Step>

  <Step title="Check tool and MCP-server attribution">
    Pivot by **Tool**. A tool that triggers expensive model turns is a cost centre even though it
    prices nothing itself.
  </Step>

  <Step title="Settle any change as an experiment">
    Swapping to a cheaper model is a quality decision. Prove it on real history first — see
    [Continuous Improvement](/manage-your-agents/optimize/continuous-improvement).
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Continuous Improvement" href="/manage-your-agents/optimize/continuous-improvement">
    Turning a cost opportunity into a settled, promoted change.
  </Card>

  <Card title="Fleet health" href="/manage-your-agents/optimize/fleet-health">
    Cost beside reliability, per agent and per window.
  </Card>

  <Card title="Runs & evidence" href="/manage-your-agents/run/runs-evidence">
    A single run's usage record, and what it did to earn it.
  </Card>

  <Card title="Observability & OTel export" href="/manage-your-agents/optimize/observability-otel-export">
    Token volume as an operational signal in your own backend.
  </Card>
</CardGroup>


## Related topics

- [Optimize — how it works](/manage-your-agents/optimize/how-it-works.md)
- [Observability & OTel export](/manage-your-agents/optimize/observability-otel-export.md)
- [Kubernetes Cost](/modules-and-workflows/cost-optimization/k8s-cost.md)
- [Support](/reference/support.md)
- [Fleet health](/manage-your-agents/optimize/fleet-health.md)