Surrogate-Key
The HTTP Surrogate-Key response header is an unofficial header containing space-separated cache tags (keys) used for targeted cache 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.
The CDN strips the header before forwarding the response to the client. Browsers and downstream caches never see the tag values. This keeps the tagging system internal to the CDN layer while giving the origin fine-grained control over Caching invalidation.
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.studio-5b.com 61a5eab8047d8c4441511cc3 pageId:62065d2eef13606e5f3d5cfa 62b9beebd61fa67c9688e708
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
Takeaway
The Surrogate-Key header attaches cache tags to CDN responses, enabling tag-based purging where a single invalidation request removes all cached pages associated with the changed content, without knowing every affected URL.