Data freshness

Data freshness is how long ago the data you are reading was actually collected. For anything that changes, it matters more than availability — and it is the measure most status pages do not publish.

Uptime is the wrong question

A collector can return HTTP 200 for days while collecting nothing. Every health check passes, the dashboard is green, and the numbers are from last week.

This is why our status page publishes hours-since-last-successful-collection per source and is never cached, rather than showing an uptime percentage. An uptime badge on a data product is close to meaningless — a silent failure at the system level.

Cached is not stale

Two different things get called the same word:

• Cached — the answer was collected recently and is being reused. You know its age, and the age is small.
• Stale — the answer is older than it should be, usually because a fresh collection failed.

A good API tells you which you got. Ours returns a cached flag on every response, so a caller can distinguish a 50-millisecond cache hit from a live fetch without guessing from the latency.

Serving stale on purpose

When a source blocks a fresh read, there are two honest options: return an error, or return the last good value and say how old it is. Silently serving old data as current is the dishonest third option, and it is common.

We take the second route only when the caller opts in, with an explicit header naming how much staleness they will accept — because whether a four-hour-old follower count is useful depends entirely on what the caller is doing with it, and they know and we do not.

Freshness is what makes a series comparable

For a time series the requirement is stricter than "recent". Every point has to be collected on the same cadence, or the gaps become indistinguishable from real change. An hourly archive with a missing hour is not an hourly archive, which is why we record windows that returned nothing separately from windows that errored — visible per source under sources.