Data Freshness

gfin uses Cloudflare edge cache, KV cache, and request coalescing to keep common Google Finance reads fast while avoiding duplicate origin requests.

Most shipped routes currently use:

• ttl_seconds: 3600
• stale_seconds: 43200

The response metadata and cache headers show the actual cache state for a given request.

Cache States

Common meta.cache values include:

Value	Meaning
miss	gfin fetched fresh data from origin.
edge	Cloudflare edge cache served the response.
kv	KV cache served the response.
stale	A stale cache entry was served because fresh origin data was unavailable.
coalesced	Another request refreshed the same cache key first.

Force Refresh

Pass refresh=1 to bypass gfin cache for that request:

curl "https://api.gfin.dev/v1/search?q=apple&refresh=1"

Use refresh sparingly. It spends origin-miss quota and increases latency. For production polling, prefer normal cached reads unless the user explicitly asks for the latest available result.

Freshness Strategy

• Use cached reads for UI page loads, dashboards, and agents that can tolerate a short delay.
• Use refresh=1 for explicit user refresh actions.
• Treat stale responses as usable but label them in time-sensitive interfaces.
• Keep meta.generated_at, meta.cache, and x-gfin-request-id in logs.