Caching
GET responses are cached at the edge per API key. Data changes weekly at most — an hour of caching is always safe.
What the API sends
Successful GET responses carry:
Response headers
Cache-Control: public, s-maxage=3600, stale-while-revalidate=86400
Vary: X-API-Keys-maxage=3600— shared/edge caches may serve the response for an hour without re-fetching.stale-while-revalidate=86400— after the hour, a stale copy may be served while a fresh one is fetched in the background (up to a day).Vary: X-API-Key— caches are keyed per API key; one key can never receive another key's cached response.
What this means for clients
- Cached responses bypass the API entirely — they do not count against your rate limit and cost nothing.
- You can cache aggressively on your side too: an hourly refresh cadence will never serve meaningfully stale data (tax data changes weekly at most; supplements land year-round but are not time-critical).
- Errors are never cached — a failed request is always a real round-trip.
Freshness and provenance
Rather than promising real-time data, every record carries its own freshness metadata (as_of, verified_at, confidence). Treat those fields — not the cache age — as the source of truth for how current a value is. See Provenance & data quality.
Planned: Redis + data_version
A Redis cache-aside layer keyed by a global
data_version (bumped on ingestion) is planned; when it lands, invalidation becomes instant after each ingestion run instead of waiting out the edge TTL.