Skip to content
LightHouse Docsv0.8.0

Reproduce the figure

View as Markdown

You can check every saving LightHouse shows in three steps of increasing depth: read the figure with its method, recompute it from the per-lever read, and recompute it from your raw records.

All examples use a viewer key and your tenant’s service token, as in Authentication.

1. The API call that returns the figure

Section titled “1. The API call that returns the figure”

GET /api/v1/savings/headline?period=YYYY-MM returns the month’s headline and every lever, each with its baseline, method, conservative choices, coverage and detail. Omit period for the current month.

Terminal window
curl "https://$AAL_TENANT.atlanticagenticlabs.com/api/v1/savings/headline?period=2026-10" \
  -H "Authorization: Bearer $AAL_KEY" \
  -H "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
  -H "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET"

What to look at in each lever:

  • status: ok (counted), included (already inside another lever), partial_comparison (a figure, not counted), or why there is no number (no_data, no_price_card, no_comparison, no_cost_feed).
  • coverage: how much of your estate reported what the lever needs. A saving on 40% coverage is a saving on 40% of your work.
  • detail: the lever’s own working. For routing, detail.source is decisions or counterfactual.

The same document is in LightHouse at Insights → Savings, and through MCP as the savings tool with view=headline. See the Savings Headline reference.

2. Recompute a lever from its own read

Section titled “2. Recompute a lever from its own read”

Each lever has a read that carries the inputs to its formula.

Lever Read What it carries
Retrieval GET /api/v1/retrieval stuffing: stuffed_tokens, sent_tokens, tokens_avoided, usd_uncached, usd_cached, the baseline used, and the same by agent, pack, index, model and day
Model routing GET /api/v1/routing Every decision with its candidates and their costs; totals with saving_usd, escalation_usd and off_saving_usd
Prompt caching GET /api/v1/caching Tokens by kind and the price card, by model, agent, pack, deployment and provider
Infrastructure and ephemeral GET /api/v1/deployments/profiles Each deployment’s profile and its estimated always-on cost

Most take format=csv for a spreadsheet.

Example: the caching lever, by hand

Section titled “Example: the caching lever, by hand”

This recomputes the caching saving for each model from GET /api/v1/caching and compares it with LightHouse’s own figure. Run it with the BASE and HEADERS from step 1.

doc = httpx.get(f"{BASE}/caching", params={"since": "2026-10-01", "until": "2026-10-31"},
                headers=HEADERS).json()
M = 1_000_000
for row in doc["by_model"]:
    card = row["price"]
    if not card or card["cache_read_per_m"] is None:
        print(row["key"], "no cache-read price: saves nothing")
        continue
    inp = card["input_per_m"]
    read_rate = card["cache_read_per_m"]
    write_rate = card["cache_write_per_m"] if card["cache_write_per_m"] is not None else inp
    mine = (row["cache_read_tokens"] * (inp - read_rate)
            - row["cache_write_tokens"] * max(write_rate - inp, 0)) / M
    print(f'{row["key"]:<45} mine {mine:10.4f}   LightHouse {row["saved_usd"]:10.4f}')

A model that more than one deployment calls on different price cards can differ slightly here, because LightHouse prices each deployment on its own card. Group by deployment (format=csv&group_by=deployment) to compare exactly.

3. Recompute from your raw records

Section titled “3. Recompute from your raw records”

For the deepest check, export your tenant (Setup and admin → Data export; see Leaving). records.jsonl holds every telemetry record LightHouse stores for you, one per line, with its type, deployment, ts and attrs. The manifest’s SHA-256 lets you show the file is the one LightHouse produced.

This recomputes retrieval’s tokens avoided for a month, by the formula on How a saving is calculated:

import json
from collections import defaultdict


DEFAULT_WINDOW = 200_000
records = [json.loads(line) for line in open("records.jsonl", encoding="utf-8")]
month = [r for r in records if r["ts"].startswith("2026-10")]


# The smallest context window among the priced models each pack called.
window_of = {}
for r in records:
    if r["type"] == "models":
        limits = r["attrs"].get("limits") or {}
        w = limits.get("context_tokens") or limits.get("context_window")
        if w:
            window_of[(r["deployment"], r["attrs"]["model"])] = w
called = defaultdict(set)
for r in month:
    if r["type"] == "model_call" and r["attrs"].get("outcome") != "refused":
        called[(r["deployment"], r["attrs"]["pack"])].add(r["attrs"]["model"])


def window(deployment, pack):
    known = [window_of[(deployment, m)] for m in called[(deployment, pack)] if (deployment, m) in window_of]
    return min(known) if known else DEFAULT_WINDOW


avoided = measured = unmeasured = 0
for r in month:
    if r["type"] != "retrieval":
        continue
    a = r["attrs"]
    corpus = a.get("corpus_tokens_in_scope")
    if corpus is None:
        unmeasured += 1          # a search that did not report its scope counts nothing
        continue
    measured += 1
    stuffed = min(corpus, window(r["deployment"], a["pack"]))
    weight = 1 / (a.get("sample_rate") or 1)
    avoided += max(stuffed - a["context_tokens_sent"], 0) * weight


print(f"tokens avoided: {avoided:,.0f} over {measured} searches ({unmeasured} unmeasured)")

Compare tokens avoided with stuffing.tokens_avoided from GET /api/v1/retrieval for the same dates. Multiply by your input price (or your cache-read price, if you cached that month) per million to get the dollar figure.

The script takes each model’s context window from any models record; LightHouse uses the deployment’s newest complete snapshot, which matters only if a window changed during the month.

Days are your tenant’s calendar days in its time zone in LightHouse’s reads; the script above uses UTC dates, so a search near midnight can fall in a different month. Set your tenant’s time zone to UTC, or filter by your own zone, for an exact match.

Comparing with LightHouse’s figure

Section titled “Comparing with LightHouse’s figure”

If your figure and LightHouse’s differ:

  1. Check the period and time zone first: LightHouse buckets days in your tenant’s time zone.
  2. Check coverage: searches or calls that reported nothing are counted by LightHouse as unmeasured and given no saving.
  3. Check the price card: LightHouse uses each deployment’s newest complete snapshot, not today’s provider list price.
  4. If they still differ, tell your certified forward-deployed engineer, with the period and the lever. A disagreement between two calculations is a bug in one of them, and we want to know which.