Cache-Tags allow a website owner to add tags to items cached at Cloudflare’s edge. The purpose is for a Cloudflare Enterprise customer to be able to purge cached content with the specified cache-tags.
How do Cache-Tags work?
- First, a user adds tags to web content by adding a Cache-Tag HTTP response header to their traffic.
- Then, the user sends web traffic through Cloudflare.
- Cloudflare associates the tags listed in the Cache-Tag HTTP header with content it is caching.
- A customer can purge Cloudflare’s cache of all cached content with a specific cache-tag either through the dashboard or the API.
- Cloudflare will force a cache miss on content with the purged cache-tag.
Adding the Cache-Tag HTTP Response Header
To get started, add Cache-Tags to content by using a Cache-Tag response header.
If you are including multiple tags, they must be separated by comma. A single response may have more than one Cache-Tag header field.
Will the Cache-Tag header be shown to end users?
No, the Cache-Tag header is removed before the response is sent to the website visitor. End users of a website therefore will never see the Cache-Tag header a Cloudflare-enabled website is using.
How long can a Cache-Tag be?
The minimum length of a Cache-Tag is 1 byte. Individual tags do not have a maximum length, but the Cache-Tag header in aggregate must not exceed 16 KB after the header field name, or 1000 unique tags. The length counts whitespace and commas, but does not count the header field name.
For the cache purge, the maximum length of Cache-Tags purged in a single purge API call is 120 characters.
What characters are allowed in Cache-Tags?
The Cache-Tag header MUST accept all valid characters allowed in HTTP headers, as specified in RFC-5987.
Spaces are not allowed in Cache-Tags.
Are Cache-Tags Case Sensitive?
No, Cache-Tags are case insensitive. That is, tag1 and Tag1 are treated as the same.
How do Cache-Tags deal with whitespace and extra commas?
All whitespace before and after Cache-Tags are removed from the header before the tags are added to the cache. We will treat tag1, tag2 and tag1,tag2 as the same.
Repeating and trailing commas are removed before the Cache-Tags are applied. That is, tag1,,,tag2, is treated the same as tag1,tag2
How do you purge a Cache-Tag in the dashboard?
To purge the cache by Cache-Tag:
1. In the Cloudflare dashboard, click Caching app.
2. In the Purge Cache panel, click Custom Purge.
3. In the Customer Purge dialog, click Tag.
4. In the text box below, enter the list of tags to use for purging the cache. You can separate each tag with a comma or type a tag per line.
5. Click Purge.
How do you purge a Cache-Tag using the API?
You can read our full documentation on api.cloudflare.com. Here is a sample curl:
curl -X DELETE "https://api.cloudflare.com/client/v4/zones/ZONE_ID/purge_cache"
-H "X-Auth-Email: firstname.lastname@example.org"
-H "X-Auth-Key: API_KEY"
-H "Content-Type: application/json"
You may purge up to 30 tags in one API call, and make up to 2,000 purge API calls in every 24 hour period by default. (30 * 2,000 = 60,000 purged tags per day)