Caching

Answer repeat requests from cache.Skip the provider call.

When the same request reaches the same workflow again, ModelRiver sends back the answer it saved last time instead of calling the AI provider. You choose how long answers stay fresh, per workflow.

How caching works

Caching is off until you give a workflow a cache window. After that, it runs on every live request to that workflow.

  1. 01

    Set a cache window

    In the workflow settings, pick 15 minutes, 1 hour or 1 day. Through the API you can set any window up to a year.

  2. 02

    Match the request

    ModelRiver fingerprints each request from its project, workflow version and body. Fields that change on every call, like the request ID and timestamp, are left out, so they don’t break a match.

  3. 03

    Answer from cache

    A match inside the window comes straight back, with no provider call, and the response is marked as cached.

  4. 04

    See what it saved

    Each hit is logged at $0, next to what the call would have cost. The workflow’s cache dashboard adds up hits and money saved.

The numbers

What it looks like

No new endpoint and no code changes. Send requests the way you already do; cached answers come back in the same shape.

request
// Same workflow, same request body: answered from cache
POST /v1/ai
{
  "workflow": "support_reply",
  "messages": [
    { "role": "user", "content": "How do I reset my password?" }
  ]
}

// Need a fresh answer this time? Skip the cache for one call
{ "workflow": "support_reply", "messages": [ … ], "cache": false }
cached response
HTTP/1.1 200 OK
x-modelriver-cached: true

{
  "data": { … },
  "meta": {
    "cached": true,
    "duration_ms": 0,
    "used_model": "gpt-4.1-mini"
  }
}
  • A window for each workflow

    Give a busy FAQ workflow a long window and a news summary a short one. Clear the window to turn caching off for that workflow.

  • Skip it when you need to

    "cache": false on a request sends that one call to the provider, even if a cached answer exists.

  • New version, fresh cache

    The workflow version is part of the match, so after you publish a change, old answers aren’t reused.

Good to know

Frequently asked questions

Does a cache hit count as a request?

Yes. A cache hit has no provider cost, but it counts as one request toward your plan’s monthly requests, the same as a call that reaches the provider.

What makes two requests the same?

They go to the same workflow version in the same project, and their request bodies match. Per-call fields such as request_id, timestamp, cache and session_id are ignored when matching.

How do I skip the cache for one request?

Send "cache": false in the request body. That call goes to the provider, and the rest of your traffic keeps using the cache.

What happens to cached answers when I publish a new version?

The workflow version is part of the match, so requests to the new version start with an empty cache and call the provider.

Does caching work with streaming or sessions?

No. Streaming requests and requests that are part of a session always go to the provider, and so do Playground runs.

How do I see what caching saved?

Cache hits show up in your request logs with a price of $0 and the price the call would have cost. Each workflow’s cache dashboard shows its cache hits, money saved and average saved per hit for today, 7 days or 30 days.

Turn on caching for one workflow

Start on the free plan, set a cache window, and watch repeat requests come back from cache.