Caching
How Marvin2 response caching works for classification and repeat requests.
X-Marvin2-Cache header
POST /marvin2 (classification) returns a cache header on every successful response. Other Marvin2 endpoints (for example POST /co-tenant) do not use this header today.
Classification responses include one of:
X-Marvin2-Cache: HIT
X-Marvin2-Cache: MISS
X-Marvin2-Cache: BYPASS
X-Marvin2-Cache: REFRESH
| Value | Meaning |
|---|---|
HIT | This response was returned from cache — the same request was classified recently. |
MISS | This response was generated fresh and saved for future matching requests. |
BYPASS | You sent X-Marvin-Cache: bypass — a fresh classification ran and nothing was read from or written to cache. |
REFRESH | You sent X-Marvin-Cache: refresh — a fresh classification ran and the new result was stored for future matching requests. |
Log these values in your integration to explain latency differences and to verify deduplication in batch runs.
Bypassing cache
To force a fresh classification without changing the request body, send an optional request header:
X-Marvin-Cache: bypass
Use bypass when you need a guaranteed fresh run and do not want the response stored in cache (for example, auditing or A/B comparisons against a prior cached result).
To recompute and replace the cached entry for the same request body, send:
X-Marvin-Cache: refresh
Omit the header for normal behavior: Marvin2 returns a cache hit when the full request body matches a recent successful classification.
When responses are cached
Caching is based on the full request body. If every meaningful field matches a previous call — company name, location, predictionType, responseConfig, searchMode, and the rest — you should see a HIT (unless you sent X-Marvin-Cache: bypass or refresh).
Change any value in the body and you should expect a MISS and a new classification.
Only successful responses are cached. Errors are not stored. bypass skips cache writes; refresh and default MISS paths store the new result.
Repeat requests
Batch and replay jobs — Re-running the same file often produces many HIT responses and much lower latency than the first pass.
Live underwriting — When a user edits company details, update the request body so the service can return an updated classification.
Need a fresh result with the same body? — Send X-Marvin-Cache: bypass or refresh instead of tweaking fields only to defeat the cache.
Quota and billing
- A
MISS,BYPASS, orREFRESHruns a full classification and typically counts toward your quota like a normal request. - A
HITreturns a stored answer without running classification again. How cache hits affect quota depends on your organization's agreement — confirm with your account team if cost control matters.
Include responseId and the cache header value when contacting support.