← All products

CDN and Caching

The Cloudflare CDN caches content in Cloudflare data centres and serves it to clients from the location selected by anycast routing. This page documents the cache decision path, the Cache Rules configuration model, purge behaviour, documented limits and plan availability.

Document control

Dana
Technical writer, Integrity Czech Republic s.r.o.

Overview

A content delivery network stores copies of content at locations near clients and serves requests from those copies, reducing round-trip distance and reducing the number of requests that reach the origin server. The effect on page load time depends on the proportion of requests that can be served from cache and on the size and dependency structure of the page.

Cloudflare states that its network operates in 348 cities and that it is within 50 ms of 95 percent of the internet-connected population (https://www.cloudflare.com/network/, retrieved 2026-08-28). That is a network reach figure, not a guarantee for a specific client population.

The Cloudflare CDN shares its data path with TLS termination, the WAF, DDoS mitigation and Workers. A request is handled once at the edge and is subject to all configured controls in a defined order, which removes the need to chain separate delivery and security intermediaries.

Architecture

Anycast routing directs a client to a nearby Cloudflare data centre. TLS terminates there, the security phases execute, and the cache decision is then made.

The cache decision proceeds as follows:

1. Determine cache eligibility. By default Cloudflare caches a defined set of static file extensions and does not cache HTML. Cache Rules override this.
2. Compute the cache key. The default key includes the host, scheme, path and query string, and can be modified with custom cache keys where the plan permits.
3. Look up the object in the local cache. On a hit, serve it and record the freshness state.
4. On a miss, with Tiered Cache enabled, request the object from an upper-tier data centre before contacting the origin. Without Tiered Cache, contact the origin directly.
5. On an origin response, apply the configured edge TTL and browser TTL, then store the object if it is cacheable.

Tiered Cache creates a hierarchy so that origin fetches are consolidated. An object fetched once by an upper tier can serve subsequent misses from lower tiers, which reduces origin request volume and improves hit ratio for long-tail content. Cache Reserve, an add-on backed by R2, adds a persistent storage layer for objects that would otherwise be evicted.

Uncacheable traffic still transits the same path: TLS terminates near the client, connections to the origin are reused, and Argo Smart Routing, where enabled, selects a middle-mile path based on Cloudflare's measurements rather than default routing.

Capabilities

Configuration model

Cache behaviour is configured with Cache Rules in the ruleset engine. A Cache Rule has an expression and a set of cache settings. The settings that most commonly matter are:

• Cache eligibility. Eligible for cache or bypass cache.
• Edge TTL. Either derived from origin headers, or overridden, including per status code.
• Browser TTL. The value written to the response for downstream caches.
• Cache key. Which components of the request contribute to identity, for example specific query parameters, headers, cookies or device type.
• Serve stale. Whether stale content may be served while revalidating or when the origin errors.
• Bypass on cookie. Expressed as a Cache Rule condition on the cookie field.

The origin remains authoritative for cacheability unless a rule overrides it. Cache-Control, Vary, Set-Cookie and status code all affect whether a response is stored. A response carrying Set-Cookie is not cached by default, which is the usual reason HTML caching appears not to work on a session-bearing application.

Cache tags are set by the origin in a Cache-Tag response header and are the basis for tag-based purge. Plan the tag scheme before enabling HTML caching, because retrofitting tags requires an origin change.

Limits and constraints

Purge rate limits from https://developers.cloudflare.com/cache/how-to/purge-cache/, verified 2026-08-31. These limits are applied per account and are shared across zones on the same plan tier.

The per-second URL thresholds are calculated as a moving average. The higher per-request allowance on Enterprise applies to single-file purge only; the maximum operations per request for tag, hostname, prefix and purge-everything is 100 on every plan, including Enterprise.

Further constraints:

• Cloudflare's self-serve subscription terms restrict the use of non-Enterprise plans for serving video and for a disproportionate share of large non-HTML files, and reserve the right to limit or disable service in those cases. Video and large-file delivery should use Stream, Images, R2 or an Enterprise agreement. Read the terms before designing a delivery architecture on a self-serve plan (https://www.cloudflare.com/terms/, retrieved 2026-08-28).
• Maximum cacheable file size differs by plan. Confirm the current value at the source before relying on edge caching for large objects.
• Purge propagation is a distributed operation. Cloudflare does not publish a guaranteed completion time, so treat purge as prompt but not instantaneous, and prefer versioned asset filenames where correctness depends on immediate replacement.
• Custom cache keys and higher purge-by-tag limits are Enterprise features.
• Serving content during an origin outage requires explicit configuration: Always Online, or serve-stale settings in a Cache Rule. It is not inherent in caching.
• Cache hit ratio depends on the content mix and on cache key cardinality. Adding query parameters or cookies to the cache key multiplies the number of stored variants and reduces hit ratio.

Plan availability

Deployment

Prerequisites.

• Classify content: static assets, anonymous HTML, personalised HTML, authenticated responses, APIs and large media files.
• Record the current cache-related response headers emitted by the origin, including Cache-Control, Vary and Set-Cookie.
• Identify the cookie or header that reliably distinguishes an authenticated session from an anonymous visitor.
• Record baseline measurements: cache hit ratio if any, origin request rate, origin bandwidth and a page-load metric from real users.
• Confirm that the intended content mix is permitted on the target plan under the applicable terms, in particular for video and large files.

Staged validation. Apply the intended Cache Rules to a non-production hostname or to a limited path prefix first. Verify cache status headers on responses, confirm that authenticated responses are bypassed, and confirm that no response containing personalised content is stored.

Configuration.

1. Enable Tiered Cache.
2. Write Cache Rules for static assets with long edge TTLs, relying on versioned filenames for invalidation.
3. Write a Cache Rule for anonymous HTML that bypasses cache when the session cookie is present, and set a conservative edge TTL.
4. Set the cache key explicitly for paths where query parameters are used for tracking rather than content selection, removing those parameters from the key.
5. Add Cache-Tag headers at the origin for content groups that will need targeted purge.
6. Configure serve-stale settings and, where appropriate, Always Online, so that origin failure has a defined behaviour.
7. Integrate purge into the deployment pipeline: purge by tag or by URL after a release, and reserve purge-everything for exceptional cases.

Cutover. Widen the Cache Rules from the validation scope to full production in stages, starting with static assets, then anonymous HTML for a subset of paths, then the remainder. Leave one business cycle between stages.

Verification.

• Confirm that authenticated pages return a bypass cache status and that no personalised content is served to a second client.
• Confirm carts, checkout and account pages behave correctly for a logged-in session in a clean browser profile.
• Confirm that cache hit ratio and origin request rate moved as expected against the recorded baseline.
• Confirm that a pipeline purge invalidates the intended objects and no others.
• Load-test the origin at the reduced request rate to confirm capacity assumptions.

Rollback. Disable the affected Cache Rule and purge the paths it covered. Because a rollback does not remove already-served responses from downstream caches, keep browser TTLs short during initial rollout so that an error has a bounded lifetime in client caches.

Operational considerations

Monitor cache hit ratio, origin request rate and origin error rate together. A hit ratio that falls without a configuration change usually indicates increased cache key cardinality, new query parameters from a marketing campaign, or a change in origin response headers.

Treat Set-Cookie on a cacheable response as an incident condition. It usually indicates that a session is being created on a page intended to be anonymous, and it will suppress caching or, if overridden, risk cross-user content exposure.

Keep purge operations within the documented rate limits and design the pipeline to purge by tag rather than by enumerating URLs, so that release size does not scale purge volume linearly.

Where Logpush is available, export cache status fields with request logs so that hit ratio can be analysed by path and by content type rather than at zone level only.

Failure modes to plan for: a new personalisation feature deployed on a cached path, a change to the session cookie name that invalidates the bypass condition, and an origin that begins emitting Cache-Control: no-store after a framework upgrade.

Known caveats

• Unmetered bandwidth is subject to the published terms. Serving video or a disproportionate share of large files on a self-serve plan is restricted, and Cloudflare reserves the right to limit or disable service in those cases.
• Resilience to an origin outage is not automatic. It requires Always Online or serve-stale configuration, and the content served in that state may be older than the last publish.
• Purge is prompt but not contractually immediate. Where replacement must be certain, change the URL rather than purging it.
• Caching HTML without a reliable authenticated-session condition risks serving one user's personalised page to another. Validate the bypass condition before widening scope.
• Adding cookies or headers to the cache key can reduce hit ratio sharply. Custom cache keys are Enterprise only.
• Page Rules are legacy. Documentation and blog posts describing cache configuration through Page Rules should be translated into Cache Rules.
• Image Resizing is now delivered under Cloudflare Images; older names and code samples may not match the current product.
• Early Hints support depends on client behaviour and has changed across browser versions. Verify current support before treating it as a delivered optimisation.

Interoperability

Cache Rules execute in the ruleset engine after the security phases, so a request blocked by the WAF is never cached or served from cache.

Workers can read from and write to the cache through the Cache API and can implement custom cache logic. Where both a Cache Rule and a Worker act on the same request, the documented traffic sequence determines precedence.

Cache Reserve is backed by R2, and R2 can also serve as an origin for the CDN, which allows an object storage backed site with no conventional origin server.

Argo Smart Routing affects only the connection between the Cloudflare edge and the origin, so it changes behaviour for cache misses and uncacheable traffic, not for cache hits.

Cloudflare Images and Stream handle media that self-serve plan terms exclude from general CDN delivery.

FAQ

Can HTML be cached? Yes, using a Cache Rule that makes HTML eligible for cache and bypasses the cache when a session cookie is present. The reliability of the bypass condition determines whether this is safe.

Why is a response not being cached despite a Cache Rule? Check for Set-Cookie on the response, a Cache-Control directive that forbids storage, a Vary header with high cardinality, or a non-cacheable status code. The cache status header on the response identifies the reason.

What is the recommended invalidation strategy for a release? Use versioned filenames for static assets so that no invalidation is required, and purge by cache tag for HTML and other content that keeps a stable URL.

References

• https://developers.cloudflare.com/cache/, retrieved 2026-08-28.
• https://developers.cloudflare.com/cache/how-to/cache-rules/, retrieved 2026-08-28.
• https://developers.cloudflare.com/cache/how-to/purge-cache/, retrieved 2026-08-28.
• https://developers.cloudflare.com/cache/how-to/tiered-cache/, retrieved 2026-08-28.
• https://developers.cloudflare.com/cache/advanced-configuration/cache-reserve/, retrieved 2026-08-28.
• https://developers.cloudflare.com/argo-smart-routing/, retrieved 2026-08-28.
• https://developers.cloudflare.com/images/, retrieved 2026-08-28.
• https://developers.cloudflare.com/rules/reference/page-rules-migration/, retrieved 2026-08-28.
• https://www.cloudflare.com/terms/, retrieved 2026-08-28.
• https://www.cloudflare.com/network/, retrieved 2026-08-28.

Content snapshot: 2026-08-28.

Changelog