# What the measurement itself costs

Shadow duplicates, cache embeddings and evaluator calls are spend too. The metacost surface is the line item most tools leave out.

Source: https://tokentriage.com/docs/build/cost-metacost

---
import Callout from '../../../components/Callout.astro';
import Details from '../../../components/Details.astro';
import NextSteps from '../../../components/NextSteps.astro';

Most of what makes this system's figures trustworthy costs money. Shadow duplication sends a
second copy of a request to a cheaper tier so a routing claim has a counterfactual behind it.
Semantic caching embeds prompts. An evaluator grades answers so a quality bound means something.

All three are LLM calls, and all three are on your bill. A cost tool that reports on your spend
while quietly excluding its own is producing a smaller number than the truth, and the gap grows
exactly as you turn on more of the things that make it credible.

So the measurement gets its own line.

## What it counts

| Source | What it is |
|---|---|
| `shadow` | duplicate requests sent to a second tier, plus the grader's own calls |
| `response_cache` | embedding calls made by semantic caching |
| `eval:<id>` | one line per configured evaluator |

Each line carries its spend for the period, and when a cap is configured for that period, the cap
and the burn percentage against it. Every line also carries a list of disclosures: why a dollar
was excluded, why a cap is not comparable to a spend, or what a drop-and-count ledger counted.

An honest-empty response is the normal state on a deployment that has none of this switched on:

```json
{
  "sources": null,
  "provenance": {
    "rows": 0,
    "source": "scan",
    "window": { "since": "2026-08-10T00:00:00.000Z", "until": "2026-08-11T00:00:00.000Z", "tz": "UTC" }
  }
}
```

No sources, because nothing was spending on measurement. That is a different statement from
`$0.00` and it is rendered differently.

<Callout type="key">
A source whose whole window is unpriced reports **UNKNOWN**, not zero. If every shadow duplicate
in a window ran against a model the price table could not price, the metacost is unknown and says
so: the same rule as everywhere else in this section, applied to the system's own spending.
</Callout>

## Two numbers called metacost

There are two, they differ, and knowing which you are reading matters.

**`GET /metacost`** is the surface described above. It includes the grader's own spend.

**`metacost_usd`**, the query metric you can group and bucket like any other, is shadow
duplicates plus cache embeddings, and it has never summed the judge.

The difference is not small. The judge's spend has been measured at 98.7% of the shadow
duplication bill on the project's own corpus, because grading an answer costs about as much as
producing the duplicate you are grading. So a `metacost_usd` series and the metacost surface can
differ by nearly a factor of two on a deployment with a judge configured.

If you are charting measurement spend over time, `metacost_usd` is the metric to use and it is
rollup-servable, but subtract nothing from the surface's total on the assumption they agree.

## Reading it against the saving

The number this surface exists to enable is a ratio nobody else publishes: what you spent to find
out what you could save, against what you saved.

Shadow duplication is the interesting case because it is genuinely expensive. Every sampled
request becomes two, and if a judge is grading, closer to three. That is what buys a routing
claim that can clear the evidence bar rather than sitting on the frontier. It is also a bill in
the meantime, and it should have an end.

The healthy shape is a spike and a decline: turn shadow duplication on, collect enough graded
rows to license the tiers you care about, promote, and turn the sampling rate down. A metacost
line that has been flat for six months is either a deliberate continuous-evidence choice or a
sampling rate somebody forgot about.

<Callout type="warning">
Shadow duplication has its own daily cost cap, `shadow.duplicate.max_usd_per_day`, and the
sampler stops when it is exhausted. Set it before you turn sampling on. Metacost tells you what
you spent; the cap is what stops you spending it.
</Callout>

## What can go wrong

**You compare metacost to a saving from a different window.** They are two figures over two
periods, which is the same trap [the realized measurement](/docs/build/cost-realized) refuses to
fall into. Quote both over the same window or quote neither.

**Your headline spend and your provider bill differ by roughly your metacost.** They should not —
duplicate and grading calls are proxied requests and are in the ledger like everything else. If
they are missing from a total you are comparing, check whether the filter behind it excluded
them.

**A cap reads as though it were a budget.** The period on a metacost line is disclosed precisely
because a cap quoted against a different period is not comparable. Check the `period` field before
reading a burn percentage.

<Details summary="Why this is not filed under overhead">

TokenTriage's *processing* overhead, the latency it adds to a request, is a separate measured
claim with its own conditions, and it lives in
[benchmarks](/docs/reference/benchmarks). This page is about dollars spent on LLM calls that
exist only because you are measuring, which is a different quantity with a different unit.

Keeping them apart matters because they trade against each other in opposite directions: sampling
less shadow traffic lowers your metacost and weakens your evidence, and neither of those is a
latency question.

</Details>

<NextSteps items={[
  {title: "How to read a cost figure", href: "/docs/build/cost-figures", description: "The rules this surface follows, including why an all-unpriced window reports UNKNOWN."},
  {title: "After you apply: the realized measurement", href: "/docs/build/cost-realized", description: "What the measurement spend buys: a saving that was measured rather than modelled."},
  {title: "Two kinds of cache savings", href: "/docs/concepts/cache-accounting", description: "The other side of the response cache's ledger: what it costs to embed, and what it avoids."},
  { title: "Observability overhead", href: "/docs/build/observability-performance", description: "Understand the measured performance and overhead of gateway observability." },
]} />