Freshness is a feature: staying within 48 hours of EDGAR
Filings & Fundamentals carries a contractual SLA: data never more than 48 hours behind publication at the source. An SLA is only as good as the machinery behind it — here's the caching, refresh, and observability stack that keeps it.
Two tiers, honest TTLs
Not all EDGAR data changes at the same rate, so we don't cache it as if it does. Ticker and company maps — which change rarely — are cached for 7 days. Submissions, company facts, XBRL concepts, and frames are cached for 24 hours. The cache itself is two-tier: in-memory for hot entries, Cloudflare R2 for everything else, with the SEC as the origin of last resort. If the R2 binding is ever unavailable, the connector degrades to direct fetch rather than failing.
Stale-while-revalidate
When a cached entry expires, we don't make your agent wait. The stale entry is served immediately while a background refresh re-fetches from EDGAR — so an SEC outage never fails your call. Honesty matters here: the response flags _meta.freshness.stale: true whenever this happens, and every tool result carries _meta.freshness with the cache tier, the cache timestamp, and the stale flag. Agents can see exactly how fresh their data is and decide for themselves.
A nightly refresh, run by a workflow
Waiting for user traffic to trigger refreshes means the first caller of the day pays the latency. Instead, a scheduled workflow calls a key-gated POST /admin/refresh endpoint every night at 03:00 MDT. The endpoint re-fetches the ticker maps and every R2 entry past its TTL — stalest first — bounded by object count and a four-minute wall-clock cap, tolerating per-company errors so one bad fetch never fails the run. The run reports {ok, refreshed, skippedFresh, errors[]}, and the workflow fails loudly if ok isn't true.
Freshness you can watch
The refresh run records its aggregates, and the connector serves them back as a public, keyless status document: service version, tool count, cache state, and the last refresh timestamp. It's there for humans checking our SLA — and for agents deciding whether this connector is healthy enough to buy. An SLA you can verify is worth more than one you have to take on faith.