データ提供
新鮮度は、リクエストパラメータ。
すべてのデータエンドポイントが freshness（cache | default | live）と max_age（秒）を受け付けます。呼び出しごとに選択できます：安価なキャッシュ読み取りに固定する、プラットフォームの鮮度ウィンドウに任せる、あるいは上流への新規取得を強制する。すべてのレスポンスが、どの層が応答したかと課金額を正確に報告します。
3つのストラテジー、1つのパラメータ
freshness=cache
プラットフォームキャッシュのみから応答します — このモードでは取得パイプラインには構造的に到達しません。
- レイテンシ
- 最速：キャッシュ読み取り 1 回、上流ホップなし。
- 課金
- そのケイパビリティのキャッシュティア Credits — 多くのケイパビリティで基本価格の半額。
- ミス時 / 失敗時
- 404 DATA_NOT_FOUND。上流は呼ばれず、代わりの取得も行われません。
freshness=default
プラットフォームが鮮度ウィンドウに基づいて判断します：新しいキャッシュは直接応答、期限切れエントリは stale として応答しつつ重複排除済みのバックグラウンド更新を実行、いずれもなければ上流から取得します。
- レイテンシ
- キャッシュヒット：高速。上流取得：上流への往復 1 回（同時呼び出し元で共有）。
- 課金
- キャッシュからの応答（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 }
}コンソールの利用台帳は同じ数値を呼び出しごとに分解するので、1 か月のトラフィックを行単位で照合できます。