Cache and purge
Configure edge cache, browser cache, cache keys and negative caching, and purge by URL, wildcard or the whole site.
Cache settings are on the Cache tab of a site's detail page (/cdn/domains/<domain>/cache). They apply to every hostname on the site. Click Save settings at the bottom after you make changes. To make new content take effect immediately, use Purge cache in the top-right corner.
Edge cache
| Setting | Description |
|---|---|
| Edge cache | Automatic: cache based on the origin's response headers. Enable: caching enabled. Disable: nothing is cached at the edge. |
| Serve stale cache on origin failure | If the origin times out or returns 500/502/503/504, the edge serves the expired cached copy instead of an error page. On by default. |
| Cache TTL mode | How the cache lifetime is worked out. See the next table. |
| Cache TTL (seconds) | The configured value the TTL mode works with. Shortcut buttons fill in 1 hour, 1 day or 7 days. |
Cache TTL modes:
| Mode | Behavior |
|---|---|
| Follow origin or use default | Use the lifetime from the origin's Cache-Control / Expires headers. If the origin gives none, use the configured value. |
| Fixed | Ignore the origin and always use the configured value. |
| Follow origin | Follow the origin strictly. If the origin does not mark the response as cacheable, it is not cached. |
| Use minimum / Use maximum | Use the smaller or larger of the origin's lifetime and the configured value. If the origin gives none, use the configured value. |
Cache by file type
Under Cache by file type you can set a lifetime per file extension, for example 7 days for jpg,png,gif. The edge applies it when the origin response has no explicit lifetime (no max-age, s-maxage or Expires). If the origin does set one, the origin's value wins.
Responses that are never cached
These responses never enter the edge cache, whatever your settings:
- Responses with
Cache-Control: no-storeorprivatefrom the origin - Responses that set a cookie (
Set-Cookie) 206 Partial Contentresponses to Range requests- Requests with methods other than GET and HEAD
Browser cache
Browser cache controls whether the edge adds a Cache-Control header for browsers:
- Enable: for responses the edge has actually cached, the edge adds
Cache-Control: public, max-age=<edge TTL>if the origin sent noCache-Control. The edge TTL is how long the edge itself keeps the response, so the browser's lifetime matches the edge's. - Automatic or Disable: the edge does not add browser-cache headers.
The origin's own Cache-Control is always passed to the browser unchanged. The edge never adds a browser-cache header to any of these:
- Responses it did not cache, such as dynamic APIs
- Requests with methods other than GET and HEAD
- Responses with status 400 or higher
- Responses that set a cookie
This stops dynamic content from getting stuck in browser caches.
The most reliable way to give static assets a long browser lifetime is to have your origin send an explicit Cache-Control: max-age=... for them.
Cache key
The cache key decides which requests share a cached copy. The preview at the bottom of the section shows what the key is made of with your current settings.
Query string handling mode:
| Mode | Behavior | Example |
|---|---|---|
| Standard | Keep every query parameter as-is | ?a=3 and ?a=4 are cached separately |
| Ignore | Ignore all query parameters | ?a=3 and ?a=4 share one copy |
| Sort | Keep every parameter, sorted by name | ?b=2&a=1 and ?a=1&b=2 share one copy |
| Allowlist | Keep only the listed parameters | id,page |
| Blacklist | Drop the listed parameters | utm_source,utm_medium,ref |
Separate parameter names with commas.
You can also split the cache by these dimensions:
- Vary by device type: separate copies for mobile and desktop.
- Vary by country: separate copies per visitor country or region.
- Vary by language: separate copies per
Accept-Language. - Cache host mode: which hostname goes into the key:
- Original request: the Host the visitor requested. This is the default.
- After resolution: the hostname the site matched.
- Host header: the Host used for the origin request.
Each extra dimension can split one URL into several cached copies, which lowers your hit ratio. Only turn on the dimensions you need.
Advanced caching and negative caching
| Setting | Description |
|---|---|
| Cache by status code (negative caching) | A cache lifetime in seconds for specific status codes such as 404 or 301. This takes priority over all other TTL settings and stops error responses from hitting the origin again and again. |
| min_ttl / max_ttl | A lower and upper bound on the final cache lifetime. 0 means no bound. |
| stale_if_error | When the origin fails, keep serving expired content for this many seconds. |
| Bypass cache with Authorization header | Requests with an Authorization header skip the cache and go to the origin. |
| Honor client no-cache | Requests with Cache-Control: no-cache skip the cache. |
| Session cookies that bypass cache | Requests that carry any listed cookie, such as session or token, skip the cache. |
Origin protection (Origin Shield)
Max concurrent origin requests limits how many requests one site can have in flight to the origin at the same time. 0 means no limit.
Above the limit, the actions in Over-limit actions (sequence) apply in order:
- cache_first: serve from cache.
- queue: wait in a queue. You set the queue length and the maximum wait in milliseconds.
- challenge: show a human-verification challenge.
- block: block the request and return the Retry-After time you set.
Use it to protect origins with limited capacity.
Purging the cache
Changing cache settings does not expire content that is already cached. To make the edge fetch fresh content from your origin:
- On the Cache tab, click Purge cache in the top-right corner. The Domains list and the Overview tab also have a one-click full-site purge.
- Choose a purge type:
- Purge all site cache: remove all cached content for the site.
- Purge by URL: enter one URL per line. Use either a full URL (
https://example.com/css/app.css) or a path (/css/app.css).
- Click Confirm purge.
How purge by URL matches:
- With a query string (for example
/list?page=2): only that parameter combination's copy is purged. The query is normalized with the site's query-string mode before matching. - Without a query string (for example
/list): every query-string variant of that path is purged. - Wildcards: put a single line containing
*to purge by pattern, for examplehttps://example.com/static/*for everything under that directory. If more than one line contains*, the request becomes a full-site purge.
A purge is delivered to all edge nodes in the background and usually completes within seconds. Afterwards, check the X-Cache-Status response header with curl -I. The first request should show MISS.
Right after a full-site purge, every request goes to your origin, so origin load rises noticeably. If you only changed a few files, purge those URLs instead.
Related
- Set cache or browser lifetimes for specific paths: Page rules
- Check your cache hit ratio: Logs and analytics