Every response from our data surface carries three things alongside the numbers: when the measurement was taken, how many seconds ago that was, and what kind of measurement it is. The first two are ordinary good practice. The third is the one worth explaining.
Three kinds of when
A reading can be measured, meaning we computed it ourselves just now from data we hold. It can be retrieved, meaning we fetched it from an upstream source that publishes on its own schedule — and the timestamp then belongs to that source, not to us. Or it can be unknown, meaning we genuinely cannot establish when the underlying measurement happened.
Those are three different confidence levels and they look identical if you only publish a timestamp. A weekly figure retrieved thirty seconds ago has an age of thirty seconds by the naive measure, and it is a week old by any measure that matters.
The bug this catches
The failure mode is specific and we shipped it before we caught it: an endpoint stamping assembly time onto a figure it had merely passed through. The response was technically accurate — that was when the JSON was built — and it implied something false about the freshness of the number inside.
Publishing the kind makes that impossible to do accidentally, because somebody has to choose a value, and choosing measured for a figure you did not measure is a lie rather than an oversight.
Where it goes
On most endpoints these are fields in the body. On one, where the payload is a map keyed by symbol and there is nowhere natural to put them, they are headers instead. Same contract, different carrier, because bending the shape of the data to fit the metadata would have been the worse trade.