Purge Files from the CDN

Overview

You can use this document to learn how to purge files from the CDN. 

A purge will remove cached files from all PoP locations. After a purge, the CDN will obtain a new copy of the affected files. 

This practice is useful if your files are updated or removed from the origin. 

If you do not purge files, then the CDN will decide when to send updated files to end users.  

There are 2 purge options: 

Note: 

For most websites, a purge will take place immediately, within 1 second.

When StackPath experiences a high load, a purge may take 1 to 2 minutes to complete. 

View custom purge options 

To access purge-related options:

1. In the StackPath Control Portal, in the left-side navigation, click Sites. 
2. Locate and select the desired site. 
3. In the left-side navigation, click CDN.

There are 2 custom purge options:

Purge via the API

To purge via the API, you need:

• Bearer token
  • To learn how to obtain a bearer token, visit the StackPath Developer Portal. 
• Stack ID
  • To learn how to obtain a stack ID, visit the StackPath Developer Portal. 
• Site domain name
  • The domain name is the name of the site in the StackPath Control Portal. 

Purge a single file via the API

Method: POST

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

Request body:

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

Note: 

• For the protocol, // will purge regardless of protocol, whereas https:// and http:// will only purge assets delivered over that protocol.
• For the query strings, under Cache Handling in the portal, if Query String Control is set to Cache All Query Strings, then only the asset that matches the URL exactly, including query strings, will be purged. 
  • To purge all versions of the asset, set the recursive option to true. Review the following example: 

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

Purge a directory recursively via the API

Method: POST

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

Request body:

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

Purge by header via the API

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"
         }
       ]
     }
   ]
}

Note: 

In the request body above, (?i) tells the CDN to match the header with case insensitivity.

Additionally, selectorName and selectorValue allow glob-y matching. For example, x-custom-* would match x-custom-header and x-custom-test. This option allows for custom purging solutions. 

Purge all assets from a site via the API

Method: POST

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

Request body:

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

Learn about purge rate limits

To ensure operational efficiency for all users, StackPath limits the number of purge requests to 100 URIs per account every 60 seconds. Recursive purges count each request, not each file purged.

• For example, if you send a single request for a purge of 50 URIs, and then 5 seconds later you send another request for 50 URIs, then both purge calls will execute successfully. 

If you send a purge request that will exceed your purge limit, then none of the purges will take place. 

• For example, if you send a request to purge 120 URIs, then none of the URIs will be purged. 

If you use the API and you encounter a rate limit, then you will receive a 429 response, which will contain the number of seconds until you can purge again. Review the following example: 

{
   "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": ""
     }
   ]
}

Note:

If you want to raise your purge limit, please contact Support.

Related documentation

To learn more about how to purge via the API, visit the Purge Content section of the StackPath Developer Portal.