Data freshness and caching
How caching works and what the cache states in a response mean.
Every upstream answer is cached with a lifetime matched to how fast that dataset changes. A report is assembled from whatever each dataset can supply at that moment, and every dataset states where its answer came from.
Cache states
Each entry in the sources panel, and in the API's sources array, carries one state:
| State | Meaning |
|---|---|
fresh | Served from the cache, still within its lifetime. |
revalidating | Served from the cache while a background refresh runs. |
refreshed | Fetched from the upstream just now. |
stale | The upstream failed, so the last known good answer was served. |
pending | Still being fetched when the response went out; cached for the next request. |
error | The upstream failed and no usable answer was cached. The failure is remembered for a few minutes, so a repeat lookup in that window returns the same result without calling the upstream again. |
Fields from a pending or error dataset read n/a, which is a missing answer and not a zero.
What meta reports
| Field | Meaning |
|---|---|
generatedAt | When the report was assembled. |
durationMs | How long assembly took. |
cacheHit | At least one dataset came from the cache. |
fullyCached | Every dataset came from the cache. |
partial | At least one dataset was pending or failed, so the report is incomplete. Always true when pendingDatasets or failedDatasets is above zero. |
pendingDatasets | How many datasets were still being fetched when the report was sent. |
failedDatasets | How many datasets failed with nothing cached to fall back on. |
retryAfterMs | How long to wait before repeating the lookup, in milliseconds. Reads n/a when the report is complete. |
omittedAnnouncements | How many routing announcements were left off the timeline for size. Truncation is never silent. |
Late datasets
A slow dataset is not waited for. It is marked pending and its answer is cached for the next lookup. On the streaming endpoint the completed report arrives on the same connection once the late dataset lands.
When to come back
A partial report says both what is missing and whether waiting helps. pendingDatasets counts datasets still being fetched: those finish in the background and land in the cache, so a repeat lookup picks them up within seconds. failedDatasets counts datasets whose source did not answer and which had nothing cached to fall back on. Repeating immediately does not help there, because a source that has just failed is not called again for that subject until its wait expires, so an early repeat returns the same report.
meta.retryAfterMs is the wait after which the report is expected to be complete, taken across everything still missing. It reads n/a on a complete report. There is no Retry-After header on a lookup: the response is a real answer with a 200 status, just not the whole one, and the wait belongs in the body.
Forcing a refresh
The refresh=1 parameter bypasses the cache. It is reserved for operators and ignored without authorisation.