GET /v1/economic-ledgerreturns the latest eligible measurement for every active source, including outcome economics and the existing seven-day snapshot comparison.GET /v1/economic-ledger/period?from=YYYY-MM-DD&to=YYYY-MM-DDreturns the outcome-free calendar-period basis used by Overview: runtime spend, identified waste, verified savings, daily series, coverage, and active-source rows.
auditHistory authorization; it adds no new or paid capability gate. Free workspaces include that capability and receive the latest active audit per source from their entitled 30-day history. Older snapshots are not considered when selecting that latest audit. Paid workspaces receive their full-history view. The same over-member-limit workspace lock that protects other audit-history reads also applies.
Latest measurement response
Representative response shape (values are illustrative):sources row contains:
- hosted source ID, source key, and display name
- current department (
{ id, name }) ornullfor Unassigned - current
runtimePostureasvpc,on-prem,saas,local,hybrid,air-gap, ornullfor Not set - hosted audit ID and wire audit ID
- source host, environment, push timestamp, and data start/end dates
- spend, identified waste, structural waste rate, and run count
- detection coverage, pricing coverage, source stability, and the detector-coverage signature
- a nullable outcome rollup
outcome-tracked source spend / successful runs. The aggregate success rate is successful runs / tracked runs, where tracked runs include success, failure, partial, and unknown outcomes.
Seven-day comparison
The API selects the deterministic latest eligible snapshot per source atgeneratedAt and exactly seven days earlier. It reconstructs active eligibility from source and audit archive timestamps, then computes deltas only over the intersection of source IDs present at both cutoffs.
sourceCounts.changed and compositionDisclosure identify sources added or removed during the period. Spend deltas remain neutral. Identified-waste deltas are omitted when either side has partial or unavailable assessment, incomplete pricing, unstable source evidence, or incompatible detector coverage; wasteUnavailableReason gives the bounded reason. This prevents lower bounds from being differenced as exact values.
Outcome comparisons include only sources with tracked outcomes at both cutoffs. Cost per successful run additionally requires at least one successful run in both periods. With no prior snapshot for any current source, all deltas are unavailable.
Verified savings
verifiedSavings is separate from the ordinary seven-day KPI comparison. It includes only modeled Optimizations whose status is Validated, whose selected same-source before and after audits each cover exactly seven days, and whose stored evidence supports a causal realized-savings claim. Both periods must be inside the workspace’s entitled audit-history window and have complete pricing, full monetary-detector coverage, stable source reads, tracked outcomes, and non-declining successful runs. The current comparison must resolve the Optimization’s same detector-versioned high-confidence finding and total runtime spend must decrease.
Validated Optimizations are grouped by source and comparison pair. Finding identities are deduplicated, and each pair contributes at most the smaller of matched resolved-waste reduction and baseline runtime spend - after runtime spend. Regressed, archived, partial, unpriced, unstable, outcome-degraded, incompatible, or non-seven-day comparisons contribute nothing.
When no modeled Optimization is Validated, amountUsd is null with unavailableReason: "no_validated_optimizations". When validations exist but none has an eligible exact comparison, the reason is "no_exact_comparison". Consumers must not render either state as $0 saved.
Verified-savings calculations continue to use existing stored audit summaries and Optimization lifecycle records. Runtime posture is separate current source metadata backed by forward-only migration 0034; the migration adds a nullable constrained column to the workspace source registry and does not backfill existing sources. Current Push v7 can add optional workflow waste and finding-change detail without changing the wire version; earlier Push v7, v6, and stored history remain readable, and pushes never assign or overwrite posture.
The posture on each Economic Ledger source row is the workspace’s current admin-assigned value, not a historical measurement fact. Xerg never infers it from framework, brand, host, collection environment, or audit evidence. The authenticated GET /v1/sources/runtime-postures route returns zero-filled active and all-source counts for the six fixed values plus Not set directly from the workspace source registry, independently of audit-history eligibility.
Calendar-period ledger
Use the additive period route when the question is about a calendar range rather than each source’s latest measurement:from and to are required, inclusive UTC dates. The immediately preceding range with the same number of dates is the comparison period. A range that includes the current UTC date is marked in progress and its deltas are suppressed, because a partial day is not comparable with completed days. The maximum is 30 days for a workspace with the ordinary Free history limit and 90 days for a full-history workspace. Invalid, reversed, future, over-limit, or history-ineligible ranges are rejected rather than silently narrowed.
The route starts with every current active runtime source. For each source and activity date, it selects the latest eligible audit_daily_coverage row by measurement push time and stored row ID. This coverage-window basis prevents overlapping rolling audits from being added together. It also means a source can remain in sources with periodMeasurement: null and No data in period instead of disappearing or contributing a fabricated zero.
The period contract contains only these metrics:
knownSpend: the sum of priced daily evidenceidentifiedWaste: the sum of supported daily waste evidence, withwasteRaterecomputed from aggregate waste and runtime spendverifiedSavings: qualified immutable validation facts whosevalidationDatefalls inside the selected range
status of exact, lower_bound, or unavailable. Coverage separately reports active and measured sources, measured and missing source-days, partial source-days, and priced versus unpriced calls. Positive identified waste can be a proven lower bound; a partial or unavailable zero is never presented as a conclusive finding. Missing dates have a null value so charts render a gap rather than zero.
Each eligible delta contains the current and prior amounts, the absolute change, and a nullable relative rate. Relative change is null when the prior amount is zero. Runtime-spend deltas (the knownSpend response field) use only aligned source-days from both periods, expose the excluded source-day count, and are suppressed if pricing is incomplete on either side. Identified-waste deltas additionally require complete period coverage, full detector assessment, stable sources, and compatible detector evidence on both sides; a lower bound is never differenced as though it were exact. No prior measurements or an in-progress current day produces a bounded deltaUnavailableReason instead of an invalid difference.
Immutable validation facts
Verified savings in a period is prospective. Migration 0035 establishes a workspace-independent availability timestamp and does not backfill mutable historical Optimization state. Each action that validates or revalidates an Optimization atomically records the evidence as either qualified or unqualified. The fact freezes the validation date, source, before/after measurement identities, finding identity, bounded evidence result, and any qualified amount. Submitting the same evidence again is idempotent. Revalidating with changed evidence creates a new fact. Regressing or archiving the Optimization later does not rewrite the fact that was observed at validation time. Soft-archiving a retained before or after measurement also does not erase its stored evidence: an accepted validation can still freeze it when the measurement remains inside the workspace’s history entitlement and satisfies the same tenant, source, runtime-kind, and comparison checks. Only positive qualified facts recorded at or after the advertised availability timestamp contribute toverifiedSavings.valueUsd; unqualified facts remain evidence for why no exact amount was claimed. When a selected period or UTC day crosses that exact timestamp, post-epoch qualified savings remain visible as lower_bound, the KPI shows ≥, earlier dates remain unavailable, and the period delta is suppressed. Fully post-epoch dates retain exact, no-validation, and no-exact-evidence states. A savings delta compares only sources with reportable qualified facts in both periods and reports current, prior, intersection, and excluded source counts plus a disclosure when the cohorts differ. factHistoryAvailableFrom, validation counts, qualification counts, and bounded unavailable reasons let clients distinguish partial or unavailable pre-ledger history from a fully covered period with no validations or no exact evidence.
Qualification retains the existing strict standard: same-source before/after measurements with declared exact seven-day windows, complete pricing and monetary-detector coverage, stable evidence, a matching detector-versioned high-confidence finding resolved in the current measurement, no same-family high-confidence regression, tracked outcomes with non-declining successful runs, and lower runtime spend. Duplicate findings are deduplicated and the total for one comparison pair cannot exceed the observed spend reduction.
Dashboard presentation
Overview uses the period route. Its three keyboard-operable KPI tabs—runtime spend, identified waste, and verified savings—select one daily chart series without another request. A compact current action follows. Department or runtime-posture waste rates use one shared neutral scale with a fleet marker; warning color is reserved for exact rows that are above an exact fleet rate. Exact dollars remain visible, lower bounds retain≥, and no unfilled track is described as efficient spend. The outcome-free Source Performance table retains every active source and labels missing evidence No data in period.
The default is the last seven completed UTC dates ending yesterday. If that implicit first load has no measured source-days but the current UTC date has data, Overview extends the range through today once, discloses the in-progress day, records the state in the URL, and suppresses deltas. An explicit date selection never auto-extends. Audit Detail continues to present outcomes, daily Performance, and workflow economics. Compare keeps Measurement A as baseline and Measurement B as current and continues to include cost-per-successful-run and success-rate rows.