How-To Purge files from the StackPath CDN

When you Purge your files from StackPath's CDN, your cached file(s) are removed from all StackPath Points of Presence(PoPs). Purging asks the CDN to obtain a fresh copy of the specified files before serving any more requests to end-users. Purging is particularly useful when files are updated on or removed from your Origin. Without the ability to purge, you are left waiting for StackPath to decide when updated files should be delivered to your users.

StackPath Portal Purge

Here are a few different methods you can use to fit your purging needs, all of which are available on the control.stackpath.com portal under Sites > Website Domain > CDN:

Purge Everything

Purge Everything is the simplest way to handle file removal from CDN. This function removes all files on your Site from all PoPs globally. The operation takes less than a second for most Sites.

You should exercise caution before using this option if your Site has files that should stay cached. Once purged, there is no option to retrieve the removed data. 

Custom Purge

Purge by URL

Purge by URL is used to purge individual files from cache. This feature, as the name suggests, requires the URL of an exact file to be purged. Upon execution, the specified file is removed from all of our PoPs. You may list up to 30 individual URLs at a time.

If you have caching by vary header or if you have dynamic caching by header turned on, you may have multiple cache keys. In that case, check the box that says "Purge Dynamic Content".

If the Pull Protocol setting is set to "HTTP or HTTPS" you will need to match the protocol you wish to purge.

Purge by Path

A Purge by path, also known as a recursive purge, can be issued to purge all content in a particular path or to purge all variations of a file using dynamic content caching. When performing a recursive purge, all files downstream of the submitted path are purged. 

Note: The Purge Everything option is just a domain root recursive purge. 

Purge using the API

You can also purge assets through the API. To purge via the API, you will need the following items:

1. Bearer token
2. Stack ID
3. Site domain name

This guide walks through how to get a bearer token and find a stack ID. The domain name is the name of your site on control.stackpath.com.

Our API reference has a lot of details about this specific endpoint, but here are a few examples to get you started:

API - Purging a Single File

Purging via cURL, you would send this request:

METHOD: POST

Endpoint: https://gateway.stackpath.com/cdn/v1/stacks/{stack_id}/purge

Request body:

{
  "items":[
    {
      "url":"//<domain_name>/path/to/file"
    }
  ]
}

Breaking this down, there are a couple of things to keep in mind for the url:

1. Protocol: "//" will purge regardless of protocol, whereas "https://" and "http://" will only purge assets delivered over that protocol
2. Query Strings: If you have Query String Control set to "Cache All Query Strings", this will only purge the asset which matches the url exactly, including query strings. To purge all versions of the asset, you will need to set the recursive option to "true":

{
  "items": [
    {
      "url":"//<domain_name>/path/to/file",
      "recursive":true
    }
  ]
}

API - Purging a Directory Recursively

Purging a directory recursively (wp-content, for example), can be done with this request:

METHOD: POST

Endpoint: https://gateway.stackpath.com/cdn/v1/stacks/{stack_id}/purge

Request body:

{
  "items": [
    {
      "url":"//<domain_name>/path/to/directory/",
      "recursive":true
    }
  ]
}

API - Purging by Header

Purging files with a specific header from a directory recursively, can be done with this request:

METHOD: POST

Endpoint: https://gateway.stackpath.com/cdn/v1/stacks/{stack_id}/purge

Request body:

{
   "items": [
     {
       "recursive": true,
       "url": "//<domain_name>/path/to/directory/",
       "purgeSelector": [
         {
           "selectorName": "(?i)<header_name>",
           "selectorValue": "<header_value>",
           "selectorType": "HEADER"
         }
       ]
     }
   ]
}

There are some interesting things about the header purge option specifically:

1. (?i) tells the CDN to match the header with case insensitivity.
2. Both the selectorName and the selectorValue allow glob-y matching (i.e. x-custom-* would match x-custom-header and x-custom-test).

This option allows for some custom purging solutions that would not otherwise be possible.

API - Purging All Assets from a Site

As noted above, purging an entire site is just a specific case of purging a directory recursively:

METHOD: POST

Endpoint: https://gateway.stackpath.com/cdn/v1/stacks/{stack_id}/purge

Request body:

{
  "items": [
    {
      "url":"//<domain_name>/",
      "recursive":true
    }
  ]
}

Purge Rate Limiting

To ensure operational efficiency for all customers, StackPath limits the number of purge requests to 100 URI’s per account every 60 seconds. Recursive purges count each request, not each file purged. If you have a need to raise your purge limit, please contact Support via hi@stackpath.com.

When a single request for a purge containing 50 URIs is sent, and then another request containing 50 different URIs gets sent 5 seconds later, both purge calls will execute successfully and will not be rate limited. 

If any purge request is sent that would exceed your purge limit, none of the purges will be completed. E.g., You submit a request with 120 URIs, the first 100 will not be executed.

If you do encounter a rate limit when purging via the API, you will receive a 429 response containing the number of seconds until you can purge again:

{
   "code": 8,
   "message": "Too many CDN purge requests received. Please retry this request in 56 seconds.",
   "details": [
     {
       "@type": "stackpath.rpc.RetryInfo",
       "retryDelay": "56s"
     },
     {
       "@type": "stackpath.rpc.RequestInfo",
       "requestId": "75529166c9690116",
       "servingData": ""
     }
   ]
}

How long does it take to Purge?

On most websites purging will appear instantaneous. The commands you issue are sent out globally in a few dozen milliseconds are queued to be removed and are removed when at the top of the purge queue. At best, this process takes less than a second. When our service is under high load, purging may take 1-2 minutes.

If you have any additional questions or concerns, please contact our Support team through live chat after logging into https://control.stackpath.com.