Data delivery
Freshness, as a request parameter.
Every data endpoint accepts freshness (cache | default | live) and max_age (seconds). Choose per call: pin cheap cached reads, let the platform decide within its freshness windows, or force a fresh upstream fetch. Every response then reports exactly which layer served you and what it cost.
Three strategies, one parameter
freshness=cache
Serves from the platform cache only — the acquisition pipeline is structurally unreachable in this mode.
- Latency
- Fastest: a single cache read, no upstream hop.
- Billing
- The capability's cache-tier Credits — on most capabilities half the base price.
- On a miss / failure
- 404 DATA_NOT_FOUND. No upstream is called and nothing is acquired on your behalf.
freshness=default
The platform decides: a fresh cache entry serves directly, an over-age entry serves stale while one deduplicated background refresh runs, otherwise the data is acquired upstream.
- Latency
- Fast on a cache hit; one upstream round trip on acquisition, shared across concurrent callers.
- Billing
- Cache-tier Credits on cache serves (stale-with-refresh included); base price on fresh acquisitions and entity-store hits.
- On a miss / failure
- Falls through to acquisition — a miss stays invisible unless every provider fails (502 UPSTREAM_ERROR).
freshness=live
Cache and entity store are skipped entirely; the provider is called for a fresh fetch which then backfills the cache.
- Latency
- Always a full upstream round trip — the slowest path by design.
- Billing
- Base price, times the capability's live multiplier where a pricing rule sets one.
- On a miss / failure
- A failed live fetch returns 502 UPSTREAM_ERROR — stale data is never masqueraded as fresh.
Side by side
| Dimension | cache | default | live |
|---|---|---|---|
| Data source | Platform cache only | Cache → entity store → provider | Provider, always |
| Latency | Lowest — no upstream hop | Low on a cache hit; an upstream round trip on acquisition | An upstream round trip on every call |
| Billing | Cache-tier Credits | Cache-tier on cache serves, base price on acquisition | Base price |
| On a miss | 404 DATA_NOT_FOUND | Acquires upstream | 502 UPSTREAM_ERROR |
max_age: a per-call freshness window
max_age bounds how old a cached or stored entry may be, in seconds. Precedence: freshness > max_age > the platform's own TTL window. Set max_age=0 to reject anything that was not fetched on this very call.
GET /v1/x/users/newdev?max_age=300 # serve cache/db entries at most 5 minutes old; # anything older triggers acquisition (default mode)
Every response tells you what happened
meta.freshness reports the effective mode, the data age in seconds, the serving layer (cache | db | upstream) and whether an over-age entry was served stale. meta.billing reports the charged Credits and whether the serve was a cache hit — no guessing after the fact.
"meta": {
"freshness": { "mode": "default", "age_seconds": 781,
"source_layer": "cache", "stale": false },
"billing": { "amount_credits": 100, "cache_hit": true }
}The usage ledger in your console breaks the same numbers out per call, so a month of traffic reconciles line by line.