Clear CDN resource cache by URL, pattern, or all and check purge history
Purge is an option that allows clearing the CDN resource cache. Using Purge is helpful if you update the content on your origin and don’t want to wait until the content is updated on CDN servers naturally because it takes time. After Purge is applied, the outdated CDN server’s cache will disappear. Additionally, the option assists if your end-users receive incorrect content of your website data from CDN servers.
We provide three options for cache clearing:
- Purge by URL (recommended) to remove content that belongs to a particular URL from the cache without impacting other cached items.
- Purge all to remove all data from the cache.
- Purge by pattern to remove content selectively by specifying path patterns with the operator that can replace any number of symbols.
There are two ways to clear the cache: via API (use the API documentation to get more information about the request) and in the Customer Portal.
Configure purge in the customer portal
1. Go to the Purge request section.
A new page will open. Perform the remaining steps there.
2. Select the relevant CDN resource from the dropdown menu.
3. Select the desired purge type and follow the instructions below (by URL, all, or by pattern).
4. Click the Purge button.
Warning
You can make two purge requests per resource per minute. One purge request is limited to 100 URLs. Therefore, you can remove up to 200 files from the cache per minute.
In the text area, specify one or more content URLs to purge, entering one URL per line. Links must:
- Start with a slash (/).
- Not include a protocol, domain name, or wildcard (*).
- Include query strings if the CDN resource cache is configured to consider the query string.
For example, to purge the file https://www.example.com/pictures/icon.jpg?size=small, specify /pictures/icon.jpg?size=small.
We recommend avoiding this method and instead using other types of Purge in the following cases:
- Your origin contains a Vary HTTP response header. When you use Purge by URL, it will delete only one version of the file.
- Large file delivery optimization is enabled. When you update several files in origin without clearing the CDN cache, Purge by URL will delete only the first slice (with bytes=0…).
The configuration of Purge by URL also depends on the settings in the Ignore Query string option:
- If the value is “Ignore All”, don’t specify parameters in the Purge request.
- If the value is “Ignore All Except”, only files with the parameters listed in the option will be cached as different objects. Files with other parameters will be cached as one object. In this case, specify the listed parameters in any order in the Purge request. Other parameters shouldn’t be specified.
- If the value is “Ignore Only”, files with the parameters listed in the option will be cached as one object. Files with other parameters will be cached as different objects. In this case, specify other parameters (if any) besides the ones listed in any order in the Purge request.
Warning
You can make two purge requests per resource per minute. One purge request is limited to 100 URLs. Therefore, you can remove up to 200 files from the cache per minute.
In the text area, specify one or more content URLs to purge, entering one URL per line. Links must:
- Start with a slash (/).
- Not include a protocol, domain name, or wildcard (*).
- Include query strings if the CDN resource cache is configured to consider the query string.
For example, to purge the file https://www.example.com/pictures/icon.jpg?size=small, specify /pictures/icon.jpg?size=small.
We recommend avoiding this method and instead using other types of Purge in the following cases:
- Your origin contains a Vary HTTP response header. When you use Purge by URL, it will delete only one version of the file.
- Large file delivery optimization is enabled. When you update several files in origin without clearing the CDN cache, Purge by URL will delete only the first slice (with bytes=0…).
The configuration of Purge by URL also depends on the settings in the Ignore Query string option:
- If the value is “Ignore All”, don’t specify parameters in the Purge request.
- If the value is “Ignore All Except”, only files with the parameters listed in the option will be cached as different objects. Files with other parameters will be cached as one object. In this case, specify the listed parameters in any order in the Purge request. Other parameters shouldn’t be specified.
- If the value is “Ignore Only”, files with the parameters listed in the option will be cached as one object. Files with other parameters will be cached as different objects. In this case, specify other parameters (if any) besides the ones listed in any order in the Purge request.
Warning
You can make one purge request per resource per minute.
Warning
Purging all files from the cache will cause a significant load on your server as CDN servers will pull all files from the origin. Therefore, if you have a large amount of content, we recommend using Purge by URL or pattern.
To purge all files from the cache, select the “Purge All” option and click the Purge button.
Warning
You can make one purge request per resource per minute. One purge request is limited to 10 patterns.
To purge files by pattern, specify the path to the file you want to purge or a path pattern without a domain name in the input line. Use the * operator, which replaces any number of symbols in your path. You can use several * operators in one request. A path must start with / or * and each path must be on a separate line.
If you don’t specify a query string, files with all the possible query string parameters will be purged from the cache according to the path pattern.
Several types of patterns are available:
| Type and explanation | Purge target | Purge pattern |
|---|---|---|
| 1. Purge the selected file Specify a file path without a domain name. As a result, all files at cdn.site/static/image.jpg will be purged, including files with query strings (for example, .jpg?VERSION).If you only want to purge a selected file with a query string, specify it in the file path: /static/image.jpg?VERSION. | cdn.site/static/image.jpg | /static/image.jpg |
| 2. Purge the group of files from one folder Input pattern without a domain name and use the * operator: /statiс/* | cdn.site/static | /statiс/* |
| 3. Purge the group of files with a certain type Input the * operator and the file name extension .jpg. As a result, all .jpg files will be purged, including files with query strings (for example, .jpg?VERSION). | cdn.site/*.jpg | *.jpg |
| 4. Purge the group of files having a common folder in the path Input path pattern without a domain name and use the * operator twice. | cdn.site/*/static/* | */static/* |
| 5. Purge the group of files with a certain type having a common folder in the path Input path pattern with the * operator. | cdn.site/*/static/*.jpg | */static/*.jpg |
Configure purge via API
We will explain in detail how to do “Purge by URL” via API calls. Examples of other Purge types (all and by pattern) can be found in the API documentation.
API request details
API request details
| Field | Value |
|---|---|
| Method | POST |
| URL | https://api.gcore.com/cdn/resources/{{resource_id}}/purge |
| URL parameter | resource_id ID of the CDN resource that the content to purge belongs to |
| Header | Authorization: Bearer {{access_token}}Content-Type: application/json |
| Payload | 1. Purge by URL:json<br/>{<br/> "urls": [<br/> "/example1.jpg",<br/> "/img/example2.png",<br/> "/style.css?ver=2.0"<br/> ]<br/>}<br/>2. Purge all: json<br/>{<br/> "paths": []<br/>}<br/>3. Purge by pattern: json<br/>{<br/> "paths": [<br/> "/images/*"<br/> ]<br/>}<br/> |
| Request parameter | paths 1. Purge by URL: (required, string) An array of one or more content URLs to purge 2. Purge all: An empty array. 3. Purge by pattern: (required, string) An array of one or more content patterns started with * or /. |
| Response | 201 Created Returns an array of the purged URLs 400 Bad Request The user has exceeded the URL quota 401 Unauthorized The user does not have the correct authentication credentials 429 Too many requests The user has exceeded the request quota |
To access the API and make authenticated requests, generate an access token. You can use a REST tool like cURL or Postman to send the requests. For this guide, we used Postman.
To send a purge by URL request:
1. In Postman, open a new request tab, then do the following:
a. Set the request method to POST.
b. Enter the resource URL in the request URL field. Replace **{{resource_id}}** with your actual value.
2. Go to the Authorization tab and do the following:
a. Select Bearer Token from the Type dropdown.
b. Copy the generated access token and paste it into the Token field.
3. Go to the Body tab and do the following:
a. Select raw as the data type.
b. Select JSON from the format dropdown.
c. Enter the payload in the text area. Replace the sample values indicated by {{ }} with your actual values.
4. Click Send.
If the purge is successful, you will receive an HTTP 201 and a response message that contains a list of purged URLs.
If an error occurs with the request, the API will return a status code and a body that contains a description of what caused the error. Here is an example:
View purge history
Info
This feature is currently in beta.
“Purge history” is the section where you can check the status of your purge requests.
Note: We’ve been keeping a history of purge requests for only one month.
To view the history, navigate to the Purge history page. The page will display all existing requests.
You can use filters to display individual reports:
- Search by CNAME. Specify the CNAME of the desired CDN resource.
- Type. Select the needed type of Purge (Purge by URL, Purge all, or Purge by pattern).
- Status. Select the desired status (In progress, Success, Failed).
- Date. Set the time period for the queries to be displayed (up to one month).