# Workflow step caching

Step caching reduces repeated external work for eligible operations. It is separate from incremental mode: incremental processing chooses an input baseline, while a cache can reuse an identical unit of work within the processing that remains.

## What can be cached

Eligible handlers declare their cache behavior. Common examples include model completion requests, web searches, and safe HTTP GET requests. Writing HTTP methods are not cached. Cookie-dependent exchanges are excluded because a seemingly identical request can depend on changing session state.

Cache identity includes the workspace, handler version, relevant configuration, and exact request content. Changing a meaningful prompt or request value creates different work. A result reused from cache should correspond to the same configured operation, not merely a similar-looking record.

## Understand freshness

A cache entry has a retention period. Typical built-in policies can retain model requests for 24 hours, web searches for one hour, and HTTP GET responses for five minutes when caching is enabled. Consult the individual step reference and workspace behavior rather than treating those durations as a universal freshness guarantee.

Only eligible successful results are stored. Errors, empty completions, oversized results, and unavailable cache storage can lead to a real execution instead. A cache miss does not mean the workflow is broken.

## Bypass intentionally

Use the supported per-step cache control, `cache: {"mode":"bypass"}`, when you need a fresh request. This is useful for verifying a changing external source or comparing behavior after an upstream service update. Bypass can increase latency and usage, particularly for model calls.

Do not use caching as an idempotency guarantee for writes. A cached read says nothing about whether a subsequent destination already received the records.

When output seems stale, inspect the request, relevant configuration, source freshness, and cache policy before changing run mode. A full run can still reuse eligible cached requests; an incremental run can still make fresh requests. See [run modes](/docs/workflows/run-modes) and [reliability](/docs/workflows/reliability).