How caching works (hit, miss, revalidate)

Every time a browser asks Cloudflare for a file, an edge node runs the same quick decision: do I already have a fresh copy? If yes, it answers in milliseconds (a cache HIT). If no, it fetches from your origin server or Worker, optionally stores the response, then serves it (a cache MISS). This guide draws that whole lifecycle as diagrams so you can picture it.

Before reading the flows, here are the five terms that show up again and again. Each one maps to a box or arrow you will see in the diagrams below.

The same URL behaves differently depending on what the edge already holds. This sequence shows the same /logo.png requested three times: first cold (MISS), then warm (HIT), then after the TTL expires (revalidate).

A cached copy has a clock on it. From the moment it is stored, it stays FRESH until max-age runs out, then becomes STALE. The next request after that is what triggers a revalidation, and the result resets the clock back to FRESH.

Cloudflare tells you which branch of the diagram a request took with a response header named cf-cache-status. These are the values you will meet most often.

You steer all of the above with one HTTP header your origin or Worker sends: Cache-Control. max-age is the browser TTL; s-maxage is the edge (shared cache) TTL and overrides max-age at Cloudflare.

# Static asset: 1 hour in browsers, 1 day on the edge
Cache-Control: public, max-age=3600, s-maxage=86400

# Serve stale instantly, refresh in the background for 10 min
Cache-Control: public, max-age=60, stale-while-revalidate=600

# Per-user / logged-in page: never cache anywhere
Cache-Control: private, no-store

export default {
  async fetch(request) {
    const body = JSON.stringify({ hello: "world" });
    return new Response(body, {
      headers: {
        "Content-Type": "application/json",
        // Browser keeps it 1h; Cloudflare edge keeps it 1 day
        "Cache-Control": "public, max-age=3600, s-maxage=86400"
      }
    });
  }
};

1. Send the header

   Deploy your Worker or configure your origin so cacheable responses carry a public Cache-Control with an s-maxage.

2. Request it twice

   Run curl -sI twice. The first is usually MISS (cold), the second should be HIT (warm) from the same edge city.

   bashcontent_copyCopy

   # -s silent, -I headers only; look at cf-cache-status
   curl -sI https://example.com/logo.png | grep -i cf-cache-status
   # 1st run -> cf-cache-status: MISS
   # 2nd run -> cf-cache-status: HIT

3. Purge after an update

   Changed the file before its TTL ends? Purge it so the next request rebuilds a fresh copy.

   bashcontent_copyCopy

   # Purge a single URL via the API
   curl -X POST \
     "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/purge_cache" \
     -H "Authorization: Bearer $CF_API_TOKEN" \
     -H "Content-Type: application/json" \
     --data '{"files":["https://example.com/logo.png"]}'

People say 'cache' for two very different things on Cloudflare. The CDN cache (this guide) is automatic and keyed by URL. Workers KV is an application cache you read and write by key from your own code. They solve different problems.

• A 200 with no Cache-Control often becomes DYNAMIC — set the header to make it cacheable.
• cf-cache-status is per edge location, so a fresh MISS in a new city is normal.
• Version your filenames (app.v2.js) so updates create a new cache key instead of needing a purge.
• Query strings change the cache key by default — /a?x=1 and /a?x=2 are cached separately.
• Use stale-while-revalidate so users never wait on a revalidation round-trip.