Cache Headers: a beginner's guide
Analyze caching configuration
HTTP caching: how websites avoid downloading the same thing twice
HTTP caching is the practice of telling browsers (and intermediate caches like CDNs) that a particular response can be stored and reused for future requests, instead of re-downloading the same file every time. The mechanism is a small set of HTTP response headers — `Cache-Control`, `ETag`, `Last-Modified`, `Expires`, and a few others — that the server sends along with each response. Together they let the server say things like "this image is fine for the next year," "this CSS file is the same as version XYZ from last week," or "this API response is private and shouldn't be cached at all." The browser obeys these instructions and decides whether to make a fresh request or use the local copy.
You should care because HTTP caching is the single biggest reason a website feels fast on a return visit. The first time a user visits, the browser has to download every CSS file, every JavaScript bundle, every image, every font. Without caching, the second visit downloads exactly the same files all over again. With proper caching, the second visit is essentially free — the browser uses its cached copies and the page renders almost instantly. The difference between a website that feels snappy on repeat visits and one that feels slow forever is almost always cache headers.
The five things every caching audit looks at:
Static asset cache lifetimes. Long-lived files (CSS, JS, images, fonts) with versioned URLs should have very long cache lifetimes, often a year (`max-age=31536000, immutable`).
HTML cache lifetimes. HTML pages should usually have short cache lifetimes (or `no-cache` with `ETag`) so users see updates quickly.
Public vs private caching. `public` lets shared caches (CDNs, proxies) cache the response; `private` restricts it to the user's own browser. Getting this wrong leaks personalized data to other users.
Conditional requests. `ETag` and `Last-Modified` headers let the browser ask "is this still current?" and get a tiny `304 Not Modified` response if so — much cheaper than re-downloading the full file.
Cache busting via versioned URLs. The standard pattern is to put a content hash in every file name (`main.a1b2c3.js`), so any change to the file produces a new URL and the old cache entry naturally falls out.
Three questions a caching audit answers:
Are my static assets actually being cached on repeat visits, or being re-downloaded every time?
Am I accidentally caching personalized content in public caches, leaking it to other users?
After my recent CMS or framework upgrade, did the cache headers regress?
The cost of bad caching is the slow, invisible degradation of repeat-visit performance. Users don't say "the cache headers are wrong" — they just say the site feels slow. The fix is a one-time configuration pass at the server, framework, or CDN level. The HTTP caching specification is documented in RFC 9111.
The Cache Headers endpoint, in plain language
In one sentence: Analyze caching configuration
Analyzes HTTP (HyperText Transfer Protocol) caching headers to understand how content is cached by browsers and CDNs. Evaluates Cache-Control, ETag, Last-Modified, Vary, and Pragma headers. Detects CDN (Content Delivery Network) providers (Cloudflare, Fastly, CloudFront, Vercel, Akamai, Netlify) and reports cache status. Identifies conflicts, security issues, and optimization opportunities.
Don't worry if some of the words above are still unfamiliar — there's a plain-language glossary at the bottom of this page, and most of the terms link to their own beginner guides if you want to learn more.
What is actually happening when you call it
Here's what's actually happening behind the scenes when you call this endpoint:
Examines all cache-related HTTP (HyperText Transfer Protocol) headers and parses Cache-Control directives (max-age, s-maxage, no-cache, no-store, private, public, immutable, stale-while-revalidate, stale-if-error). Detects CDN (Content Delivery Network) providers and their cache hit/miss status. Identifies contradictory directives, security risks like Set-Cookie on public responses, and provides a human-readable summary of the caching behavior.
If you're using an AI assistant through MCP, you don't need to understand any of the technical details — the assistant calls the tool and translates the result for you.
Why this specific tool matters
Let's skip the marketing fluff and answer the only question that actually matters: why should you, a real human with a real to-do list, care about the Cache Headers tool? Here's the plain-English version, written the way you'd hear it from a friend who happens to do this for a living.
Proper caching reduces server load, improves performance, and saves bandwidth. Analyzing cache headers helps identify misconfiguration, contradictory directives, and security issues like sensitive data being cached by shared proxies.
Picture this in real life. Imagine a frontend developer. Here's the situation they're walking into: Debug why content isn't being cached properly by analyzing cache header configuration. Without the right tool, that person would be stuck copy-pasting between five browser tabs, reading documentation written for engineers, and crossing their fingers that the answer they cobble together is correct. With the Cache Headers tool, the same person gets a clear answer in seconds — no spreadsheets, no guessing, no waiting for someone on the infrastructure team to free up.
Three questions this tool answers in plain English. If any of these have ever crossed your mind, the Cache Headers tool is built for you:
Why does my website feel slow on real devices, even though it looks fine on mine?
Which specific change would give me the biggest speed boost for the least work?
Am I losing visitors and search rankings because of performance problems I cannot see?
You can either click the tool and get the answer yourself, or ask your AI assistant — connected through MCP (Model Context Protocol) — to ask the question for you and translate the answer into something you can paste into Slack.
Who gets the most out of this. Founders watching their conversion rates, marketers trying to lift landing-page revenue, ecommerce operators chasing every percentage point of speed, and developers tuning Core Web Vitals. If you see yourself in that list, this is one of the EdgeDNS tools you should bookmark today.
What happens if you skip this entirely. Skip it and visitors bounce, conversions drop, and your search ranking quietly slides — all from a problem nobody on the team can see. That's why running this check — even once a month — is one of the cheapest forms of insurance you can give your domain.
Available on the free plan. The technical details: `GET /v1/domain/cache`.
When would I actually use this?
If you're still on the fence about whether the Cache Headers tool belongs in your toolbox, this section is for you. Below you'll meet three real people — a frontend developer, a devops engineer, and a security engineer — facing three real situations where this tool turns a stressful afternoon into a five-minute task. Read whichever story sounds closest to your week.
Story 1: Performance Debugging
Imagine you're a frontend developer. Debug why content isn't being cached properly by analyzing cache header configuration.
Why it matters: Fix caching issues improving repeat visit performance.
Story 2: CDN Optimization
Imagine you're a devops engineer. Verify cache headers are set correctly for CDN (Content Delivery Network) edge caching.
Why it matters: Maximize CDN (Content Delivery Network) cache hit rates for better performance and lower origin load.
Story 3: Security Review
Imagine you're a security engineer. Ensure sensitive pages have proper no-cache/no-store headers.
Why it matters: Prevent sensitive data from being cached inappropriately.
Common situations across teams. Beyond the three stories above, here are the everyday workplace moments when people across the company reach for the Cache Headers tool — or one of the tools right next to it in this category. If any of these are on your calendar this month, that's your sign:
Before a high-traffic marketing campaign or product launch.
After a redesign, to make sure performance did not regress.
When your conversion rate drops without an obvious cause.
On a recurring schedule, to enforce a performance budget for your team.
If you can see yourself in even one of those bullets, the Cache Headers tool will pay for itself the first time you use it.
Still not sure? Here's the easiest test in the world. Open Claude, ChatGPT, Gemini, or any other AI assistant connected to the EdgeDNS MCP server and ask, in your own words: "Is the Cache Headers tool useful for my job?" The assistant will look at the tool, ask you a couple of follow-up questions about what you're trying to accomplish, and give you a straight answer in plain English. No commitment, no signup forms, no jargon.
The easiest way: just ask your AI assistant
If you've connected the EdgeDNS MCP server to Claude, ChatGPT, Gemini, Cursor, or any other AI assistant, you don't need to write any code. Just ask in plain English:
"Use the Cache Headers tool to check example.com and explain anything that looks wrong in plain language."
The AI will figure out which tool to call, fill in the right parameters, run it, and then explain the result back to you. No copy-pasting between tabs. No reading raw JSON. No memorizing endpoint names.
MCP (Model Context Protocol) access is free on every plan, including the free tier. One API key works for both REST and AI — you do not have to choose.
The technical way: call it from code
If you're a developer and want to call the endpoint from a script or your own application, here's the simplest possible example. Replace the placeholder API key with the real one from your dashboard.
# Replace edns_live_YOUR_KEY with your real API key from the dashboard
curl -H "Authorization: Bearer edns_live_YOUR_KEY" \
"https://api.edgedns.dev/v1/domain/cache?domain=example.com"What you need to provide
There's just one piece of information you need to provide. The table below explains exactly what it is and what a real value looks like.
| Field | Type | Required? | What it means | Example |
|---|---|---|---|---|
domain | string | Yes | The domain to analyze cache headers for | example.com |
What you get back
When you call this tool, you'll get back a JSON object with the fields below. If you're talking to it through an AI assistant, the assistant reads these for you and explains them in plain language — you don't need to memorize them.
| Field | Type | What you'll see in it |
|---|---|---|
domain | string | The queried domain |
statusCode | number | HTTP (HyperText Transfer Protocol) status code of the response |
contentType | string | Content-Type of the response |
isCacheable | boolean | Whether the response is cacheable |
summary | string | Human-readable summary of the caching behavior |
cacheControl | object | Parsed Cache-Control directives (public, private, noCache, noStore, maxAge, sMaxAge, mustRevalidate, proxyRevalidate, noTransform, immutable, staleWhileRevalidate, staleIfError) |
etag | string | ETag header value |
lastModified | string | Last-Modified header value |
vary | array | Vary header values |
expires | string | Expires header value |
age | number | Age header value in seconds |
pragma | string | Pragma header value (legacy HTTP/1.0) |
effectiveTtl | number | Effective TTL (time to live) in seconds (priority: s-maxage > max-age > expires) |
ttlFormatted | string | Human-readable TTL (time to live) duration |
cdn | object | CDN (Content Delivery Network) detection result (detected, provider, cacheStatus, edgeLocation) |
issues | array | Caching issues and conflicts detected |
recommendations | array | Caching optimization and security suggestions |
Words you might be wondering about
If any words on this page felt like jargon, here's a plain-language version. Click any linked term to read a full beginner-friendly guide.
CDN (Content Delivery Network) — A worldwide network of servers that store copies of your website close to your visitors so pages load fast.
HTTP (HyperText Transfer Protocol) — The language web browsers and websites use to talk to each other.
Need Programmatic Access?
Automate domain intelligence with 100+ API endpoints and a free MCP server for AI integration.