Cloudflare Cache Keys: A Guide for Website Owners

If Cloudflare is serving an unexpected cached variant—or you need requests with different URL details to stay separate—review the Cache Key. It is the identifier Cloudflare uses for a cached file. Include a request detail when it changes the content visitors should receive; leave it out only when those requests are interchangeable. Cloudflare documents Cache Key configuration within a Cache Rule, and its Trace tool can help show which properties were applied to a request.

What a cache key controls#

A cache key template determines which parts of a request Cloudflare uses to identify a cached file. Requests with matching keys can use the same cached copy. Requests with different keys can have separate cached versions.

Cloudflare’s default cache key includes the full URL—scheme, host, and query string—along with the Origin header and certain method and forwarding headers. Because the query string is part of the default key, URLs that differ only in their query strings are treated as different cache-key identities by default.

Custom cache keys can use selected query strings, headers, cookies, host information, device type, country, and language. These choices can separate content that genuinely varies, or combine requests that should share one cached file.

Choosing which details belong in the key#

Ask whether each request detail changes the response a visitor should receive.

Swipe or scroll horizontally to read every column →

Cloudflare warns that customizations can reduce cache hit rate or create cache sharding, where requests are split among more cache-key variants. Add only the distinctions needed to keep content correct.

The query-string decision#

Cloudflare documents an option to ignore query strings. When query strings are ignored, URLs that differ only in their query strings share a cache key. Use that behavior only when those parameters do not select different content.

For example, a tracking parameter may not change a page, so it could be excluded from the key after you confirm how the site handles it. A parameter that changes a product, language, filter, or other page content must remain represented in the cache key, either through the relevant query string or another configured property.

Configure and verify a Cache Key#

1. List the URL, header, cookie, host, or user feature that can change the response.
2. Decide which of those details must separate cached content and which are safe to omit.
3. In Cloudflare, configure the Cache Key setting within a Cache Rule. Use the default key unless a documented content variation requires a custom key.
4. If using a custom key, select the smallest set of query strings, headers, cookies, host information, or user features that preserves the required distinctions.
5. Send representative requests for each content variation and compare the returned content before applying the rule broadly.
6. Use Cloudflare’s Trace tool to identify which cache-key properties were applied to a request.

If different content is being treated as the same cached file, check whether a content-changing query string, header, cookie, host, device type, country, or language was omitted. If equivalent requests are producing too many separate variants, check whether unnecessary properties were added and whether they are causing cache sharding.

Cache Keys are a Cloudflare-specific configuration concept here: the exact controls and behavior described above come from Cloudflare’s documentation and should not be assumed for every hosting or CDN provider.

Sources#

• Cloudflare: Cache Keys
• Cloudflare Cache documentation