Segmented Caching

Fastly’s Segmented Caching feature allows you to cache resources of any size. Segmented Caching works by breaking resources into smaller segments in Fastly’s cache then recombining or splitting these resources to respond to arbitrary size byte Range: requests from clients. Once enabled, Segmented Caching improves performance for Range: requests and allows Fastly to efficiently cache resources of any size.


Fastly recommends enabling Segmented Caching on services that will be serving large resources. Without Segmented Caching enabled, the resource size limits for your account depend on when you become a Fastly customer:

  • If you created your account on or after June 17, 2020 and haven't enabled Segmented Caching, your Fastly services have a maximum object size of 20 MB.
  • If you created your account prior to June 17, 2020 and haven't enabled Segmented Caching, your Fastly services have a maximum cacheable object size of 2 GB for requests without Streaming Miss or 5 GB for requests with Streaming Miss.

How Segmented Caching works

When an end user makes a Range: request for a resource with Segmented Caching enabled and a cache miss occurs (that is, at least part of the range is not cached), Fastly will make the appropriate Range: requests back to origin. Segmented Caching will then ensure only the specific portions of the resource that have been requested by the end user (along with rounding based on object size) will be cached rather than the entire resource. Partial cache hits will result in having the cached portion served from cache and the missing pieces fetched from origin. (Requests for an entire resource would be treated as a byte Range: request from 0 to end of resource.)

Once Fastly has all of the objects necessary to respond to an end user’s request, the Segmented Caching feature will assemble the response by concatenating or pulling portions of objects. The requests back to origin, also called “inner requests,” will have a true value for segmented_caching.is_inner_req and requests from end users, also called “outer requests,” will have a true value for segmented_caching.is_outer_req. If a request is made for an object without segmented caching enabled, both variables will have a FALSE value.


The feature will only go back to origin for missing objects needed to handle the end-client’s byte Range: request. Cache hits will occur based on having that portion of resource in cache even if the end user’s range exact request is unique.

Limitations and considerations

This feature has the following limitations you should take into account:

  • Segmented Caching isn't intended for dynamically generated content. If your content isn't fully static (e.g., you have dynamic content like user-generated comments), be sure to set up purging any time the content changes to avoid any potential for data corruption.
  • Segmented Caching is not compatible with object compression and ESI. To use either of these features, you must ensure Segmented Caching is disabled.
  • Segmented Caching is not compatible with Fastly's Image Optimizer (IO). If IO is enabled, Segmented Caching is disabled automatically.
  • HTTP chunked transfer encoding between Fastly and origin isn't supported. Your origin server must frame responses to Range: requests with the Content-Length header.
  • URL purges must be authenticated. Segmented caching allows you to purge all range objects for the resource by URL purge, but authentication for URL purge needs to be enabled due to its underlying implementation. Make sure you’ve provided an authorization token for URL purges as described in our purging documentation.
  • Segmented Caching cannot be enabled based on resource size. The VCL code to enable Segmented caching must run before the resource is requested from cache, so it is not possible to know how large it will be. However, it is possible to make segmented caching conditional upon the URL (e.g. /video/) or file extension (e.g. *.m4v), and this is a common use case for resources which will benefit from it. Our instructions below contain an example of how to enable the Segmented Caching feature based on extension.

This feature also has the following considerations you should take into account:

  • Resources cached prior to enabling Segmented Caching are not used. If you are enabling Segmented Caching on an existing service, whole resources already in cache are ignored and Varnish will go back to origin to build range request objects. You can choose to purge these or ignore them to be aged out of cache.
  • Your cache hit ratio (CHR) will appear lower than it actually is because only outer requests are used in the calculation. For example, if there is a request for the first 100 MB of a resource but Fastly only has 99 MB of 100 MB in cache, the entire request will be counted as a miss in the CHR stat. In practice, only 1 MB had to be fetched from origin and you experienced 99% origin offload.

Enabling Segmented Caching

Use the following steps to enable Segmented Caching.

  1. Determine which resources should use Segmented Caching.


    We recommend focusing on a set of file extensions or a well-defined URL structure that distinguishes the resources.

  2. From the Home page, select the appropriate service. You can use the search box to search by ID, name, or domain. You can also go to CDN > CDN Services or Compute > Compute Services to access a list of services by type.
  3. Click Edit configuration and then select the option to clone the active version.
  4. Click VCL Snippets.

  5. Click Create your first VCL snippet.

  6. Fill out the Create a VCL snippet fields as follows:

    • In the Name field, enter an appropriate name (e.g., Enable segmented caching).
    • From Type (placement of the snippets) menu, select within subroutine.
    • From the Select subroutine menu, select recv (vcl_recv).
    • In the VCL field, add a VCL snippet that sets the req.enable_segmented_caching VCL variable to true in vcl_recv. For example, to ensure proper caching of the large resources you've identified that contain MPEG-2-compressed video data, you could add this VCL snippet in vcl_recv:
    1# my custom enabled Segmented Caching code
    2if (req.url.ext == "ts") {
    3 set req.enable_segmented_caching = true;

    This snippet tells Fastly to look for requests for files with the ts extension and then enable Segmented Caching for those files.

  7. Click Create to create the snippet.

  8. Click Activate to deploy your configuration changes.
Was this guide helpful?

Do not use this form to send sensitive information. If you need assistance, contact support. This form is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.