1. Home
  2. Reference documentation
  3. HTTP references
  4. HTTP Headers

Surrogate-Key

Additional, space-separated purge keys for the response.

Fastly reads this header from responses. It is proprietary to Fastly.

Setting a Surrogate-Key header on a response from a backend server tells Fastly to index that response against the specified key (or keys), as well as the cache key which is the subject of the current request. These 'surrogate keys' cannot be used to find and serve the content in a request, but can be used to target the content for purging.

For example, consider a request to an e-commerce site for /category/shoes, which elicits a response from the backend server with the following headers:

Cache-Control: max-age=86400
Surrogate-Key: product-62952 product-1043 product-14534

In the example above, the response will be cached, with the primary cache key being linked to "/category/shoes" (depending on the cache key configuration in vcl_hash), but will also be indexed against the keys "product-62952", "product-1043" and "product-14534" for purging purposes. In this use case, this allows changes to a product to automatically purge all the pages on which that product appears, and not just the product page itself.

Adding keys in VCL

While it's conventional to add surrogate keys to a response at the backend server, it's also possible to add them using VCL in vcl_fetch, by setting the value of the Surrogate-Key backend response header:

vcl_fetch { ... }
Fastly VCL
set beresp.http.Surrogate-Key = "key1 key2 key3";

Purging

To purge a group of resources that share the same surrogate key, use the web interface, or the API.

Limitations

Individual keys are limited to 1024 bytes in length, and the total length of the Surrogate-Key header may not exceed 16,384 bytes. If either of these limits are reached while parsing a Surrogate-Key header, the key currently being parsed and all keys following it within the same header will be ignored.

Debugging

Fastly will automatically strip the Surrogate-Key header from responses unless the header Fastly-Debug is present in the request. Setting Fastly-Debug: 1 on a request is one way to see which surrogate keys, if any, are associated with a resource in the cache.

Fastly
© Fastly 2024