A cache key is the unique identifier a cache uses to decide whether it already holds a saved copy of a response. When a request arrives, the CDN builds a key from parts of that request, usually the host, URL path, and selected query parameters, then checks its store for a match. A match returns the cached object instantly. No match sends the request to the origin. Get the key right, and most traffic never touches your server. Get it wrong, and you either serve stale pages or cache almost nothing. The gap between a 40% and a 95% hit ratio often comes down to a single query parameter.
Key Takeaways
- A cache key is the fingerprint a CDN generates for each request so it can look up a stored response.
- Most keys combine host, URL path, and chosen query parameters; headers, cookies, and device type are added only when they change the response.
- Two requests that produce the same key share one cached object, which is what makes a high cache hit ratio possible.
- Putting volatile values like tracking parameters in the key fragments the cache and drops the hit ratio.
- Custom cache key rules let you include, ignore, or normalize request parts so the key stays specific but stable.
- Tuning a cache key can lift the hit ratio from the 40s into the 90s, cutting origin load and improving response times.
How a Cache Key Works
A cache key is the unique string a cache generates from an incoming request and then uses to store and retrieve the matching response.
Think of it as a fingerprint for a request. The cache runs a small set of rules over the request, produces a key, and treats that key as the address where the response lives. Ask for the same thing twice, and you get the same fingerprint, so the second request is served straight from cache.
This idea sits underneath every content delivery network. For the wider picture of how edge delivery works, the guide on what is a CDN covers the full request path. The cache key is the piece that decides, at each edge location, whether a request becomes a hit or a miss. Run that traffic through a global CDN and the same key logic repeats at every edge location worldwide.
- Identifies whether a saved copy of the response already exists
- Points to where that copy is stored on the edge node
- Keeps different variants of the same URL as separate entries
What most people miss: two URLs that look identical to a human can produce different keys. A trailing slash, an uppercase host, or one extra query parameter is enough to split them into two separate cache entries.
That sensitivity is exactly why a key that is too specific quietly wrecks performance, which is the next thing worth understanding.
Why Cache Keys Matter for Speed and Accuracy
Cache keys matter because they decide whether a request is answered from the edge in milliseconds or sent on a slow round trip to your origin.
Every request resolves to one of two outcomes. The key matches something in the store, so the edge returns the object without contacting your server. Or the key finds nothing, and the request travels to the origin, waits for a response, and only then reaches the user.
A well-designed key sends most traffic down the first path. Good Caching behavior depends on it. When the key is stable, edge nodes answer for you and your origin stays quiet even during traffic spikes, which also keeps TTFB low for the end user.
| Outcome | Where It Is Served | Typical Response | Origin Load |
|---|---|---|---|
| Cache Hit | Edge node near the user | Single to low double-digit ms | None |
| Cache Miss | Origin server | Hundreds of ms plus network | Full request |
A media site we looked at ran at a 61% hit ratio. Their keys included a session cookie on every page, so logged-in and logged-out visitors never shared a cached copy. Removing that cookie from the key pushed the ratio to 93% in a day and cut origin requests per minute by roughly two-thirds.
Before you can tune any of this, you need to know exactly which parts of a request end up in the key.
What Can Be Included in a Cache Key?
A cache key can include any stable part of a request: the host, the URL path, query parameters, selected request headers, cookies, and a device or language signal.
Most CDNs start with a sensible default of host plus path plus full query string. From there you decide what to add and what to drop. The guiding question is simple. Does this element change the response the user should get? If yes, it belongs in the key. If no, keep it out.
Adding an element makes the key more specific and creates more separate cache entries. That helps when the content genuinely differs and wastes storage when it does not. This is a different job from a resolver-level cache like a DNS cache, which keys on domain names rather than full HTTP requests.
- Host and URL path: almost always included, the backbone of the key
- Query parameters: include the ones that change content such as color or page; drop the ones that do not, such as utm_source
- Request headers: include Accept-Encoding or Accept-Language when they alter the response
- Cookies: include only when a cookie truly changes the page, rarely for anonymous traffic
- Device type: include a device class when you serve different markup to mobile and desktop
The clearest way to see this is to watch a single request turn into a key, step by step.
A Cache Key Example: From Request to Stored Object
Here is a concrete example. A request for a product page with a color parameter and a tracking parameter becomes a single normalized key once the CDN applies its rules.
Take the request GET site.com/shoes?color=red&utm=spring. The raw URL carries two parameters, but only one of them changes what the user sees. color=red selects a product variant. utm=spring is a marketing tag that does not affect the page.
Sensible rules lowercase the host, keep color, and drop utm. The resulting key is site.com/shoes | color=red. Every visitor who lands on that page from a different campaign now shares the same cached object instead of generating a fresh what is a cache miss each time.
- Receive the request and read its URL, headers, and cookies
- Apply key rules: lowercase host, keep content parameters, drop tracking parameters
- Build the normalized key string
- Look up that key in the edge store
- Return the stored object on a hit, or fetch from origin and store it on a miss
One retailer we reviewed had forty campaign variants of a single landing page, each with its own utm value. Because those parameters sat in the key, the page cached forty times and rarely served a hit. Dropping the tracking parameters collapsed it to one entry.
Once you can read a key, writing the rules that shape it becomes straightforward.
How to Build Custom Cache Key Rules
Custom cache key rules come down to three actions applied to each part of a request: include it, ignore it, or normalize it.
Include the parts that change the response. Ignore the parts that never do. Normalize the parts whose formatting varies but whose meaning does not. Most configuration screens on a modern CDN or edge computing platform expose exactly these controls.
- Include: content-changing query parameters, device class, and language
- Ignore: tracking parameters, ad click identifiers, and random cache-busting values
- Normalize: lowercase the host, sort query parameters into a fixed order, and collapse equivalent encodings
Conventional advice says cache everything you can. Yes, but caching aggressively with loose keys is worse than caching less with tight keys. A loose key stores many versions that never get reused, so you pay for the storage and still serve misses.
Rules are only half the story. The payoff shows up when you measure the hit ratio and start tuning.
Cache Key Optimization: Raising Your Hit Ratio
Optimizing a cache key means removing everything that fragments it, so more requests resolve to the same stored object and your hit ratio climbs.
The single biggest lever is stripping volatile values from the key. Tracking parameters, ad click IDs, and full user-agent strings are the usual culprits. Replace an exact user agent with a device class, and you go from thousands of key variants to two or three.
A CDN boost often comes from this one change alone. Higher hit ratios also protect the origin during sudden load, and they reduce the risk of a cache stampede when many clients request the same expiring object at once.
- Strip tracking and ad-click parameters from the key
- Group requests by device class instead of full user agent
- Normalize case and parameter order
- Vary only on the headers that actually change the response
- Set time-to-live values that match how often the content changes
In the media example from earlier, tuned keys moved the hit ratio from 42% to 94%, a 52-point gain. That is not a rounding error. It is the difference between an origin that idles and one that falls over under a traffic surge.
Even with good rules, a few habits quietly undo all of this. They are worth naming.
Cache Key Mistakes That Quietly Break Caching
The most damaging cache key mistakes are the ones that look harmless: a stray parameter, an unsorted query string, or a cookie that sneaks into the key.
None of these throw an error. Your site works, pages load, and the cache appears to function. The only symptom is a hit ratio that sits far lower than it should, next to an origin that works harder than it needs to.
- Leaving tracking parameters in the key, which splits one page into many entries
- Keying on the full user agent, which creates a near-unique key per browser
- Including session cookies for anonymous traffic
- Forgetting to sort query parameters, so identical requests miss each other
- Caching content that should never be cached, which is where cache invalidation discipline matters
What most people miss: a broken key rarely shows up as an outage. It shows up as a cloud bill that keeps climbing and an origin that scales up to serve traffic the edge should have absorbed.
Fix the key and the rest of your caching strategy finally has something solid to stand on.
The Bottom Line on Cache Keys
A cache key is a small thing with outsized influence. It decides, request by request, whether your infrastructure serves content from the edge or drags it back from the origin. Get the key specific enough to be correct and stable enough to be reused, and everything downstream improves: faster responses, lighter origin load, and steadier performance under pressure.
The practical rule is short. Put content-changing elements in the key, keep volatile ones out, and normalize the rest. Audit your highest traffic URLs first, because that is where a single parameter can move the hit ratio by dozens of points. Strong caching is not about caching more. It is about building keys that let one stored response answer as many requests as possible.
Frequently Asked Questions About Cache Keys
What is a cache key in simple terms?
A cache key is the unique identifier a cache builds from a request to decide whether it already holds a matching response. If two requests produce the same key, they share one cached copy.
What is an example of a cache key?
For the request site.com/shoes?color=red&utm=spring, sensible rules keep color, drop utm, and lowercase the host, producing the key site.com/shoes | color=red. Every campaign variant then shares one cached object.
What is the cache key in Apigee?
In Apigee, a cache key is the identifier used by the ResponseCache and PopulateCache policies to store and retrieve entries. You compose it from KeyFragment elements such as a request path or query parameter, so each unique combination maps to its own cached value.
How does a custom cache key improve the cache hit ratio?
A custom cache key removes volatile values like tracking parameters and full user-agent strings, so more requests resolve to the same stored object. That raises the share of requests served from the edge, often from the 40s into the 90s.
