Surrogate-Key
Purging thousands of CDN cache entries by URL is impractical when one content change touches many pages. The Surrogate-Key unofficial response header attaches space-separated cache tags to responses, enabling tag-based purging at the CDN layer.
Usage
Cache invalidation by URL is straightforward for a single resource, but becomes impractical when one content change affects hundreds or thousands of cached pages. The Surrogate-Key header solves this by attaching tags to every cached response. When content changes, a purge request targeting a specific tag removes all cache entries carrying the tag, regardless of URL.
Fastly popularized this header as part of its instant
purge architecture. Webflow, Discord, Anthropic, and other
platforms using Fastly include Surrogate-Key values in
their responses. Each tag is an opaque identifier: a site ID, page ID,
content object reference, or a keyword like 404req
indicating the response type.
Multiple tags are separated by spaces within a single
header value.
Fastly strips the header at its edge before forwarding the response to the client, keeping the tagging system internal to the CDN layer while giving the origin fine-grained control over Caching invalidation. Other stacks pass the header through unchanged, which is why Surrogate-Key values from origins behind non-Fastly proxies show up in browser responses.
The X-LiteSpeed-Tag header serves a similar purpose for LiteSpeed-powered infrastructure, using comma-separated tags instead of spaces.
Values
Tag values are space-separated opaque strings. The origin defines the tag format. Common patterns include site identifiers, page-level content IDs, and request classification markers.
Site tags
A bare domain or site identifier (e.g.
quests.medal.tv) acts as a broad tag. Purging this tag
clears all cached responses associated with the site.
Object ID tags
Tags resembling hexadecimal strings
(e.g. 6756f478be66e4f7aa3a0203) reference specific
content objects in the origin's database. When the
object is updated, a purge targeting the object ID
removes all cached pages containing the resource.
Page ID tags
Tags prefixed with pageId: (e.g.
pageId:67f55a9666b2ae2332f5f893) identify specific
pages in the CMS. Updating a single page triggers a purge
by its page ID tag, invalidating the cached version
without affecting unrelated content.
Request classification tags
Tags like 404req or sslRedirect classify the response
type. Purging by classification tag removes all cached
responses of the same type across the site.
Example
A Webflow-hosted site returns a Surrogate-Key with a site identifier and a content object ID. The site tag covers all pages under the domain, and the object ID ties the response to a specific CMS entry. Purging either tag removes this cached response.
Surrogate-Key: quests.medal.tv 6756f478be66e4f7aa3a0203
A page-level response includes more granular tags. The
site tag, site-wide object ID, pageId: tag, and
additional content object IDs each allow targeted
invalidation at different levels of specificity.
Surrogate-Key: www.example.re 5f2a1c3d4e5b6a7f8c9d0e1f pageId:6a1b2c3d4e5f60718293a4b5 7c8d9e0f1a2b3c4d5e6f7081
A 404 response tagged for bulk invalidation. The
404req marker allows purging all cached 404 pages
in a single operation when content is added or routes
change.
Surrogate-Key: aternos.medal.tv 404req
Moving between CDNs
The tagging idea travels across vendors while the
header name and delimiter change.
Surrogate-Key separates values with spaces, and
the Cloudflare and Akamai equivalents,
Cache-Tag and Edge-Cache-Tag,
separate with commas. A migration reusing the same
tag strings still rewrites the delimiter and the
purge calls.
Cloudflare Cache Response Rules translate an origin Surrogate-Key header into Cache-Tag format at the edge, which lets a site keep its existing tagging code while the purge path moves.