資料交付
新鮮度，是一個請求參數。
每個資料端點都接受 freshness（cache | default | live）與 max_age（秒）。按次選擇：釘死便宜的快取讀取，交給平台在其新鮮度視窗內決策，或強制一次全新的上游抓取。每次回應都會如實上報服務層與本次計費。
三種策略，一個參數
freshness=cache
唯讀平台快取——該模式下取數管線在結構上不可達。
- 延遲
- 最快：單次快取讀取，無上游跳轉。
- 計費
- 按該能力的快取檔 Credits 計費——多數能力為基礎價的一半。
- 未命中 / 失敗
- 404 DATA_NOT_FOUND。不呼叫上游，也不會替你抓取。
freshness=default
平台在其新鮮度視窗內決策：新鮮快取直接回傳；超齡條目按 stale 回傳並觸發去重的背景刷新；否則向上游現場取數。
- 延遲
- 快取命中：快。上游取數：一次上游往返，並發呼叫者共享同一次抓取。
- 計費
- 快取層服務（含 stale+刷新）按快取檔計費；現場取數與實體庫命中按基礎價。
- 未命中 / 失敗
- 自動落到取數管線——除非所有供應商失敗（502 UPSTREAM_ERROR），未命中對你不可見。
freshness=live
完全跳過快取與實體庫，直接呼叫供應商抓取最新資料，隨後回填快取。
- 延遲
- 每次都是完整的上游往返——設計上就是最慢路徑。
- 計費
- 基礎價；定價規則配置了 live 倍率的能力按倍率計。
- 未命中 / 失敗
- live 抓取失敗回傳 502 UPSTREAM_ERROR——絕不把舊資料偽裝成新資料。
並排比較
| 維度 | cache | default | live |
|---|---|---|---|
| 資料來源 | 僅平台快取 | 快取 → 實體庫 → 供應商 | 永遠是供應商 |
| 延遲 | 最低——無上游跳轉 | 快取命中低延遲；取數時一次上游往返 | 每次呼叫都上游往返 |
| 計費 | 快取檔 Credits | 快取服務按快取檔，取數按基礎價 | 基礎價 |
| 未命中時 | 404 DATA_NOT_FOUND | 轉上游取數 | 502 UPSTREAM_ERROR |
max_age：按次的新鮮度視窗
max_age 限定快取/入庫條目允許多舊（秒）。優先級：freshness > max_age > 平台自身 TTL 視窗。設 max_age=0 可拒絕一切非本次抓取的資料。
GET /v1/x/users/newdev?max_age=300 # serve cache/db entries at most 5 minutes old; # anything older triggers acquisition (default mode)
每次回應都告訴你發生了什麼
meta.freshness 上報生效模式、資料年齡（秒）、服務層（cache | db | upstream）以及超齡條目是否按 stale 回傳；meta.billing 上報本次計費 Credits 與是否快取命中——事後不用猜。
"meta": {
"freshness": { "mode": "default", "age_seconds": 781,
"source_layer": "cache", "stale": false },
"billing": { "amount_credits": 100, "cache_hit": true }
}主控台的用量帳本按次拆出同樣的數字，一個月的流量可以逐行對帳。