# Freshness & sourcing

The 24-hour store, cold loads, where every figure comes from, how the series are computed and the dated history.

HTML version: https://fundfactsapi.com/docs/freshness · Updated 2026-10-25

## 5. Freshness and latency: plan for slow first calls

- A **warm** ISIN (in the store: loaded by anyone in the last 7 days) returns in well under a second with `cached: true`. Past 24 hours it also carries `stale: true` (and the header `X-FundFacts-Stale: 1`) and is refreshed after the response, usually within a minute.
- A **cold** ISIN (never loaded, or not in the last 7 days) is loaded from the fund's published documents on demand. Expect **15 seconds to 3 minutes**; the server allows up to **300 seconds**. Set your HTTP client timeout to 300 s for this endpoint. Never retry a request that is still in flight: the second call waits on the same load and burns quota.
- Two callers asking for the same cold ISIN at once share one load; the second one receives the same payload.
- `expiresAt` is `generatedAt` + 24 hours: when the payload is due for a refresh, not when it disappears. A request after it is answered at once from the store with `stale: true` while the refresh runs in the background; `?refresh=true` reads before answering, at most once an hour per ISIN. Nothing older than 7 days is served without a new read. `data.dataAsOf` is the date of the underlying figures (monthly for most funds), `generatedAt` is when the payload was produced. Show `dataAsOf` to end users, not `generatedAt`.
- **Cache locally.** Persist payloads keyed by ISIN with `expiresAt`; re-fetch only after expiry, or about a minute later when the body said `stale: true`. Pre-warm a universe with a background job (sequentially, a few in parallel at most) rather than on the user's first page view.

Full reference: https://fundfactsapi.com/llms-full.txt