Following the launch of [Cache-Tags and Purge API](https://www.netlify.com/blog/cache-tags-and-purge-api-on-netlify/), today we’re happy to announce yet another feature in the series of caching improvements that aim to give Netlify users more control over their cached content. Netlify now supports a custom `Netlify-Vary` header, which instructs Netlify’s edge on how to better cache and serve dynamic assets using Netlify’s CDN with Netlify Functions, Netlify Edge Functions or [external services proxied to using redirect rules](https://docs.netlify.com/routing/redirects/rewrites-proxies/#proxy-to-another-service). ## Why is it important? Netlify allows developers to choose which static response to be served and cached for a given request based on rules like [authentication, country or locale based conditions](https://docs.netlify.com/routing/redirects/redirect-options/), or even query parameters. This works great when serving static assets, but over the last couple of years the web ecosystem has evolved and now there’s a big trend of building dynamic applications running in serverless functions or edge functions within our system. Different types of dynamic resources may need to respect different parts of the incoming request when deciding whether to serve a cached response or not: - Some resources don’t look at query parameters and will get a much higher cache hit rate by not taking these into account, while others use specific query parameters and need the cache to take those into account. - Some resources might be cacheable depending on a cookie value (ie. no `is_logged_in` cookie might mean, “show a login page,” and `is_logged_in=1` cookie might mean, “show a logged in member page”). - Some frameworks, like Next.js, depend on varying cached responses based on the value of specific headers like `RSC`, `Next-Router-Prefetch` and `Next-Router-State`. The standard `Vary` header is very restrictive and generally meant for use cases like content negotiation, so Netlify offers a more flexible `Netlify-Vary` header, that gives fine grained control over which parts of a request need to match the cached object. ## How do cache key variations work? Netlify now supports a custom `Netlify-Vary` header, which takes a set of comma delimited instructions for what parts of the request to vary on: - `query` vary by request URL query parameters - `header` vary by the value of a request header - `language` vary by the languages from the `Accept-Language` request header - `country` vary by the country inferred from doing the GeoIP lookup on the request IP address - `cookie` vary by a value of a request cookie These instructions, together with the request URL, will define the cache key which Netlify uses to uniquely identify a cached object in our CDN. ### Query By default Netlify doesn’t take query parameters into account to construct the cache key, since things like `_utm` parameters or session IDs for analytics, social links, etc, can drastically reduce cache hit rates. However, if you know that the responses from a resource will only depend on specific query parameters, like a `item_id`, `page` or `per_page` parameter, you can change this behavior for a resource by adding `Netlify-Vary` to your dynamic content responses: ``` Netlify-Vary: query=item_id|page|per_page ``` `Netlify-Vary` will tell Netlify to take just those 3 query parameters into account when deciding whether to serve a cached response, so other query parameters like `_utm` will not affect your cache hit rate. If you’d like to include all query parameters when creating the cache key, you can achieve this by adding the following **`Netlify-Vary`** header: ``` Netlify-Vary: query ``` ### Header You can now instruct Netlify Edge to vary content on specific headers, so your business logic can be transported as a header and still influence the cache. To control which headers go into the cache key, you can use the `header` instruction like this: ``` Netlify-Vary: header=device-type ``` This will make the cache take a custom `Device-Type` header into account for the cache key and distinguish between objects with different `Device-Type` header values, so for example different users trying to access your platform from different device types (e.g. `mobile`, `web`, etc.) will see different custom content for each type of device. Similarly to query parameter variations, you can also provide a list of headers: ``` Netlify-Vary: header=device-type|app-version ``` ### Cookie Cookies serve a variety of purposes, but one of their common use cases is A/B testing. However, cookies often contain additional information, such as authentication details or analytics data. In such scenarios, you don’t want to vary the cached content on the entirety of the cookie value, but just on a couple of key-value pairs. Similarly to query variations, you can target a subset of cookie key-value parameters to be considered on the cache key: ``` Netlify-Vary: cookie=ab_test_name|ab_test_bucket ``` This will tell Netlify to vary cached content based off the values for both `ab_test_name` and `ab_test_bucket` set on the request’s `Cookie` header. ### Language & Country One of the most common use cases for cached content variations is varying the content depending on user features such as language and geolocation. To vary on the user’s language, you can specify groups of languages to take into account for your cache key. These are based on the `Accept-Language` header from the request. For example, the following instruction will keep different cache objects for users with English as an accepted language, users with German as an accepted language, and all other users. ``` Netlify-Vary: language=en|de ``` To group more languages together, use `+`: ``` Netlify-Vary: language=en|es+pt|da+nl+de ``` This will vary the cached content for clients accepting English, clients accepting Spanish or Portuguese and clients accepting Danish, Dutch or German as well as the unlisted group of all other clients. Similarly, to vary cached content based on the geographical origin of the request, you can specify groups of countries to take into account for your cache key. The following instruction will keep different cache objects for users located in England, users in Spain or Portugal and users in Denmark, The Netherlands or Germany, as well as the unlisted group of all other users. ``` Netlify-Vary: country=en|es+pt|dk+nl+de ``` ### Combine instructions You can use any combination of the above variation instructions to vary your cached content on: ``` Netlify-Vary: country=es+de|us,query ``` This will tell Netlify to take both the entire query into account for cached objects, as well as the request’s country of origin. ## Try it out today We’ve created a [demo repository](https://github.com/netlify-labs/cache-key-variations) where you can explore these patterns yourself and see them in action on Netlify Edge at [the demo site](https://cache-key-variations.netlify.app/). Visit [our documentation](https://docs.netlify.com/platform/caching/) for more information on how to get started. ## What’s next for edge caching on Netlify? We’re thrilled to have brought you all these new caching features, unlocking more complex use cases and potentially making your current caching logic for dynamic assets much simpler and intuitive. Our team is committed to making Netlify the world’s most advanced global caching infrastructure, and we’re looking forward to further evolve our platform to continue to serve your needs by building everything from simple web pages to a full-fledged web platform. ### Share - [X (fka Twitter)](https://twitter.com/intent/tweet?text=Netlify Cache Key Variations&url=https://www.netlify.com/blog/netlify-cache-key-variations/) - [LinkedIn](https://www.linkedin.com/shareArticle?mini=true&url=https%3A%2F%2Fwww.netlify.com%2Fblog%2Fnetlify-cache-key-variations%2F) - [Facebook](https://www.facebook.com/sharer.php?u=https://www.netlify.com/blog/netlify-cache-key-variations/) - [Bluesky](https://bsky.app/intent/compose?text=Netlify Cache Key Variations+https://www.netlify.com/blog/netlify-cache-key-variations/) * * * ### Tags - [changelog](/blog/tags/changelog/) - [Netlify Functions](/blog/tags/netlify-functions/) - [Serverless functions](/blog/tags/serverless-functions/) - [Netlify Edge Functions](/blog/tags/netlify-edge-functions/) ## Keep reading ![](/_astro/eb275ddb9290b947ba4c53ac30538c77b44edae9-720x405_1y2MXK.webp) News & Announcements June 25, 2026 [ ### Netlify Functions, designed for Agent Experience ](/blog/netlify-functions-designed-for-agent-experience) - ![Profile picture of Eduardo Bouças](/_astro/52958f21e8450baf6d8e60302341a984e220c0cd-512x512_13VDlu.webp) Eduardo Bouças ![](/_astro/d20f9f717bbdd511f73ee138be4114ff13f480f9-2400x1350_1fe4aq.webp) News & Announcements June 24, 2026 [ ### How we measure Netlify’s Agent Experience ](/blog/how-we-measure-netlify-agent-experience) - ![Profile picture of Sean Roberts](/_astro/bbf2243f8171dbddd80ab2103622106cef84d125-512x512_Z1d2LKE.webp) Sean Roberts ## Recent posts News & Announcements June 25, 2026 [ ### Netlify Functions, designed for Agent Experience ](/blog/netlify-functions-designed-for-agent-experience) - ![Profile picture of Eduardo Bouças](/_astro/52958f21e8450baf6d8e60302341a984e220c0cd-512x512_13VDlu.webp) Eduardo Bouças News & Announcements June 24, 2026 [ ### How we measure Netlify’s Agent Experience ](/blog/how-we-measure-netlify-agent-experience) - ![Profile picture of Sean Roberts](/_astro/bbf2243f8171dbddd80ab2103622106cef84d125-512x512_Z1d2LKE.webp) Sean Roberts Guides & Tutorials May 15, 2026 [ ### How to build a real-time AI chatbot in minutes with Netlify Agent Runners (no backend) ](/blog/how-to-build-a-real-time-ai-chatbot-in-minutes-with-netlify-agent-runners-no-backend) - ![Profile picture of Nahrin Jalal](/_astro/f0e7c8f227a03fe58340c99ef5439d5a896c0733-272x272_Z23kDpD.webp) Nahrin Jalal ![](/_astro/3f255b372fa958df35802666ee33b4609b2d71bd-1200x1586_1VtE2D.webp) ### How do the best dev and marketing teams work together? [Access the report](https://www.netlify.com/reports/2024-leadership-trend-report/access/)