Invalidate cached content

Invalidation marks cached content as stale. On the next request, Cloudflare revalidates the content with your origin. If your origin responds with 304 Not Modified, Cloudflare reuses the cached content instead of downloading it again.

Invalidation is sometimes called soft purge.

Purge and invalidation accept the same selectors: URLs, cache tags, hostnames, URL prefixes, or everything. They differ in what happens to matching content:

Use purge when cached content must not be served again. Update or remove the content at your origin before you purge it. Otherwise, the next request can cache the old version again.

Use invalidation to refresh content that might not have changed, such as a group of assets that share a cache tag.

Invalidation does not fetch new content in advance. Instead, the next request for invalidated content triggers revalidation.

To revalidate, Cloudflare sends your origin a conditional request. The request uses the ETag or Last-Modified header that your origin sent with the content. Your origin's response determines what happens next:

• If your origin responds with 304 Not Modified, Cloudflare reuses the cached content and sets a new time to live (TTL).
• If your origin returns new cacheable content, Cloudflare replaces the cached content.
• If your origin returns a 5xx error or cannot be reached, Cloudflare can serve the cached content stale. For details, refer to Stale content during revalidation.

Invalidation does not guarantee that content is reused. Cloudflare fetches the full response if the content is no longer cached, your origin sent neither header, or your origin does not support conditional requests.

A 304 Not Modified response does not refresh cache tags set by Cache Response Rules. Cache tags from your origin's Cache-Tag header are updated only if your origin includes that header in the 304 response. To refresh cache tags otherwise, purge the content.

Your cache settings and your origin's health determine whether visitors receive stale content while Cloudflare revalidates:

• With stale-while-revalidate, Cloudflare can serve stale content while it revalidates in the background.
• Without stale-while-revalidate, requests wait for revalidation to complete.
• If your origin returns a 5xx error or cannot be reached, Cloudflare can serve stale content for as long as the content stays in cache. This happens even if the response has no stale-if-error directive. To limit this, set stale-if-error in the response. To prevent it, set stale-if-error=0. With Origin Cache Control enabled, must-revalidate, proxy-revalidate, and s-maxage also prevent it.

For content that is still fresh, stale-while-revalidate and stale-if-error windows start when you invalidate it, not when it would have expired. Invalidation never extends a stale window that has already ended.

For example, suppose you invalidate a cached response with the following headers before it expires:

Cache-Control: public, max-age=3600, stale-while-revalidate=30
ETag: "product-v1"

Cloudflare can serve this response stale for up to 30 seconds after the invalidation while it revalidates. The response has no stale-if-error directive. If your origin returns a 5xx error or cannot be reached, Cloudflare can serve the response stale beyond those 30 seconds. It can do so for as long as the response stays in cache.

Other directives and Cache Rules settings can prevent Cloudflare from serving stale content while it revalidates. For details, refer to Revalidation.

Invalidation keeps matching content in Cache Reserve, where it continues to incur storage costs. If your origin responds with 304 Not Modified, Cloudflare reuses the stored content instead of fetching it from your origin again. Content served from Cache Reserve is not served stale while it revalidates, even with stale-while-revalidate.

Compared with purging, invalidation reduces origin egress but not Cache Reserve operations. Updating the stored content after a 304 response is a Class A operation. Invalidating by URL also updates the stored content when you send the request, which is a Class A operation. For details, refer to Cache Reserve operations.

Purge forces a cache miss for matching Cache Reserve content. For details, refer to Cache Reserve purge behavior.

Invalidation from the dashboard or the invalidate_cache endpoint does not affect Workers Cache. Workers Cache belongs to your Worker, not to your zone. To remove responses from a Worker's cache, call ctx.cache.purge() from the Worker.

Check the following requirements before you invalidate content:

• Origin validators: To reuse cached content, your origin must return an ETag or Last-Modified header and support conditional requests.
• Permissions: For API requests, use a token with the Cache Purge permission for the zone. To invalidate from the dashboard, your role must include the same permission.
• Rate limits: Invalidation requests count toward the purge limits for your account. For details, refer to Limits.

To invalidate all cached content, select Invalidate Everything, and then confirm.

If your zone uses Version Management, Invalidate Everything is not available. Instead, choose Everything: All cached content under Select content by, and then select Invalidate. The dashboard does not ask you to confirm this option. Invalidating everything in the Production environment applies to all environments.

If your cache key includes the visitor's device type or country, Enterprise zones can invalidate those variants of a URL from the dashboard. Select URL, and then set the device type or country under Advanced (custom cache keys). For other cache key headers, use the API.

To invalidate content, send a POST request to the invalidate_cache endpoint:

https://api.cloudflare.com/client/v4/zones/{zone_id}/invalidate_cache

The request body uses the same format as the corresponding purge request. The endpoint determines whether Cloudflare purges or invalidates the content.

In the following examples, replace $ZONE_ID with your zone ID and $CLOUDFLARE_API_TOKEN with your API token.

To invalidate specific URLs, list them in files:

curl --request POST \
  "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/invalidate_cache" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "files": ["https://www.example.com/images/product.jpg"]
  }'

If your cache key includes request headers, include the header values that identify the cached variant:

{
	"files": [
		{
			"url": "https://www.example.com/images/product.jpg",
			"headers": {
				"CF-Device-Type": "desktop",
				"CF-IPCountry": "US"
			}
		}
	]
}

For URL matching requirements, refer to Purge by single-file.

Use the request body that matches the content you want to invalidate:

Prefixes include a hostname and path, without a URL scheme.

For example, to invalidate all content tagged product-images, send this request:

curl --request POST \
  "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/invalidate_cache" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"tags":["product-images"]}'

Invalidating everything can trigger revalidation for a large amount of content as requests arrive. Select the smallest set of content that meets your needs.

For a non-production Version Management environment, include the environment ID in the path:

curl --request POST \
  "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/environments/$ENVIRONMENT_ID/invalidate_cache" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"tags":["product-images"]}'

To find the environment ID, refer to Purge zone versions via API. For production, use the zone-level endpoint.

A request to invalidate everything in a non-production environment applies only to that environment. The same request to the zone-level endpoint applies to all environments.

Invalidation requests count toward the same account-level purge limits as purge requests. The limits that apply depend on how you select content:

Purge and invalidation requests draw from the same limits. Heavy use of one reduces the capacity available for the other. Like purge limits, these limits apply per account and are shared by zones on the same plan.

Each invalidation request can include the same maximum number of items as a purge request.

To verify an invalidation, use a cacheable test URL whose origin returns an ETag or Last-Modified header. Keep the content unchanged at your origin during the test. To observe revalidation directly, omit stale-while-revalidate from the test response and set a positive TTL.

For cached content, expect the following results:

Without an ETag or Last-Modified header from your origin, Cloudflare has nothing to revalidate with, so it fetches the full response. When your origin returns 304, Cloudflare can still return 200 OK to the visitor with the cached content.

With Tiered Cache, a lower-tier data center revalidates with its upper-tier data center. A visitor can see EXPIRED or MISS even when your origin returned 304. Concurrent requests can also affect which status you observe. Use your origin logs to confirm revalidation. For status definitions, refer to Cloudflare cache responses.

Confirm that the content was cached and that your selectors match it. Also confirm that your origin returns an ETag or Last-Modified header and responds to conditional requests with 304 Not Modified.

Check these headers in a request sent directly to your origin, not through Cloudflare. When your origin sends neither header, responses from Cloudflare can still include a Last-Modified header because of smart revalidation towards users. Cloudflare does not use that header when it revalidates with your origin.

If the content was also purged after it was cached, the purge takes precedence, and the next request fetches the full response.

While Cloudflare revalidates, it serves stale content only if the cached response includes stale-while-revalidate. You can turn this off with the Serve stale content while revalidating setting in Cache Rules.

If your origin returns a 5xx error or cannot be reached, Cloudflare serves invalidated content stale by default, for as long as it stays in cache. The Cache Rules setting does not change this. To limit how long Cloudflare serves stale content when your origin fails, set stale-if-error in your origin responses. To prevent it, set stale-if-error=0. With Origin Cache Control enabled, must-revalidate, proxy-revalidate, and s-maxage also prevent it.

To stop serving cached content, purge it instead.