Controlling caching

When we store your content in cache, we calculate a Time to Live (TTL). The TTL is the maximum amount of time we will use the content to answer requests without consulting your origin server. After the TTL expires, we may keep the content in storage, but we won't use it to answer requests unless we're able to revalidate it with your origin.

There's no guarantee that the content will stay cached for the length of time specified in the TTL. Depending on the size of the object and how popular it is relative to other objects, we may delete it before its TTL expires.

For more information about controlling how long Fastly caches your resources, start with our documentation on cache freshness. In general, we will honor any Cache-Control headers you send to us from your origin.

Determining the TTL of an object

You can determine the TTL of an individual object as follows:

  • If you've set the Surrogate-Control: max-age, Cache-Control: max-age, or Expires headers, the TTL is whatever you specified in those headers
  • If you've specified the TTL in the Fastly control panel or custom VCL, the TTL is whatever you specified
  • If you've specified the TTL in the Fastly control panel or custom VCL and you've set the Surrogate-Control: max-age, Cache-Control: max-age, or Expires headers, the TTL specified in the control panel might override the TTL specified in the origin response
  • If you haven't specified the TTL in the Fastly control panel or custom VCL and you haven't set the Surrogate-Control: max-age, Cache-Control: max-age, or Expires headers, the TTL is 3600 seconds. If you use custom VCL or Fiddle, the default is 120 seconds.

You can change the fallback TTL in the service configuration.

Setting different TTLs for Fastly cache and web browsers

Purging objects from the Fastly cache is easy. Clearing the caches of users' web browsers is much harder. For that reason, it can make sense to set different TTLs for content in the Fastly cache versus users' web browsers. You can set different TTLs for the Fastly cache and web browsers through Surrogate-Control headers defined by the W3C. For example, if you wanted Fastly to cache something for a year but you also wanted to set a maximum age of a single day for users viewing that object in a web browser, then you could return the following HTTP headers:

Surrogate-Control: max-age=31557600
Cache-Control: max-age=86400

The Surrogate-Control header in this example tells Fastly to cache the object for a maximum of 31557600 seconds (one year). The Cache-Control header in this example tells the browser to cache the object for a maximum of 86400 seconds (1 day).

CDNs can't invalidate an end user's web browser cache. If your content is going to change frequently or if you want new content immediately available to end users, the best strategy is to cache that content on Fastly and specifically instruct browsers not to cache it. Then, when you purge the Fastly cache, an end user's browser will display the new version the next time the content is requested.

One way to do this is to return the following headers:

Surrogate-Control: max-age=31557600
Cache-Control: private, no-store

This Surrogate-Control header tells Fastly to cache the object for a maximum of 31557600 seconds (one year). The Cache-Control header should be added in vcl_deliver. It tells the browser not to cache the object.

For Surrogate-Control, Fastly supports the max-age, stale-if-error, and stale-while-revalidate parameters.

Setting a fallback TTL

NOTE: Fallback TTLs apply only when your origin doesn't send cache control headers. As a caching best practice, configure appropriate Cache-Control headers on all responses from your origin servers instead of relying on fallback TTLs. Use fallback TTLs as a safety net for edge cases where headers are missing.

Fastly sets a default fallback TTL that you can update at any time. Keep in mind, however, that if you're using custom VCL, the fallback TTL will already be specified in the VCL boilerplate and the fallback TTL configured via the Fastly control panel or the API will not be applied. Our documentation on cache freshness and TTLs explains this in more detail.

  1. Log in to the Fastly control panel.

  2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain.

  3. Click Edit configuration and then select the option to clone the active version.

  4. Click Settings.

  5. In the Fallback TTL area, click the pencil Pencil icon next to the TTL setting.

    Fallback TTL quick config

  6. In the Fallback TTL (sec) field, enter the new TTL in seconds.

    HINT: If there's no other source of freshness in the response, setting the fallback TTL to 0 seconds in the Fastly control panel will set return(pass) in vcl_fetch.

  7. Click Save to save your changes.

  8. Click Activate to deploy your configuration changes.

HINT: If you're setting a fallback TTL for a Google Cloud Storage (GCS) bucket, use our GCS instructions instead of these.