CDN caching and purging

ImageKit uses Amazon CloudFront CDN to deliver your media and other files faster. When you request a file from ImageKit, it is served from the nearest CDN edge server to your location, ensuring that your files are delivered quickly.

Behind the global CDN, ImageKit has processing servers in 6 AWS regions. You can select the processing region during account setup. The processing region is where your files are stored and processed. When a file is requested from ImageKit, it is cached on the CDN edge server for a certain period. This is known as CDN caching. The cached file is then served to subsequent requests for the same file without having to go back to the ImageKit server.

Besides CDN caching, ImageKit also caches the transformed images & videos to improve performance in an internal cache. Video transformations are cached permanently on ImageKit's end, while the duration of stored image transformation is limited.

If you encounter slow response times for your requests, please refer to this documentation.

You can also opt for the save a copy of assets on demand feature. If enabled, ImageKit will start caching the original files too.

When you purge the cache, ImageKit removes the cached resource from the CDN, all internal caches, and the original asset caches. This ensures that the subsequent request for the same resource fetches the latest version.

By default, ImageKit caches all files on the global CDN for a maximum time of 1 year. This means once a file is requested from ImageKit, it is cached on the CDN edge server for up to 1 year. Note that this is the maximum time a file can be cached on the CDN. The CDN can evict non-popular files from the cache before the one-year period.

After the maximum cache time elapses, the file is removed from the CDN cache, and the subsequent request for the file will fetch the file from the ImageKit server. However,

ImageKit sets the standard Cache-Control headers on the response. For example, the following Cache-Control header is set on the response for a file:

Cache-Control: public, s-maxage=31536000, max-age=31536000, must-revalidate

• s-maxage=31536000, max-age=31536000 indicates the CDN and the browser to cache the resource for 1 year. We have tested this across different browsers to ensure that caching works as expected.
• must-revalidate response directive indicates that the response can be stored in caches and can be reused while fresh. If the response becomes stale, it must be revalidated with the origin server before reuse. ImageKit sets the ETag header on the response to enable revalidation.

In Chrome, you can load a page and see the network tab in the developer tools to see how the browser is caching the resources. Please uncheck the "Disable cache" checkbox in the network tab to see the caching behavior. Also, if you issue a hard refresh (Ctrl + F5) in the browser, the browser will ignore the cache and fetch the resources from the server. In that case, you will see a 200 status code in the network tab.

When using ImageKit with external storages, you can configure the caching duration for each resource. This method does not work if you store files in the ImageKit Media Library.

You can configure ImageKit to respect the Cache-control response header sent by the origin at a URL-endpoint level. You can set the Cache-control header in object storage using the UI or programmatically. Learn more from S3, GCS, or Azure documentation. We only pick timing from the max-age directive in the Cache-control header.

For example, suppose your external storage sends a Cache-Control header to cache a file for 1 hour, i.e., public, max-age=3600. In that case, ImageKit.io applies the cache-control header across all its internal caches, generated transformations, and CDN. This ensures that the cache control you set is obeyed at all times.

If the max-age directive is missing from the origin, ImageKit caches the file for the default cache time.

You can purge the content from CDN and ImageKit intermediate cache by using the purge cache API or from the dashboard.

You can purge the cache for multiple files within a directory by appending a wildcard at the end of the URL only if ANY ONE of the following conditions are met:

1. The path consists of at least two levels of nesting:
   The path of the directory, excluding your imagekitId and URL pattern, contains at least two levels of nesting, starting from the root as shown below:
   ✅ https://ik.imagekit.io/IMAGEKIT_ID/PATTERN/LEVEL_1/LEVEL_2*
   ❌ https://ik.imagekit.io/IMAGEKIT_ID/PATTERN/LEVEL_1*

For example, the path /images/upload* is valid, but /images* is not.

2. The path length is at least 15 characters:
   The path of the directory, excluding your imagekitId and URL pattern, is at least 15 characters in length, as shown below:
   ✅ https://ik.imagekit.io/IMAGEKIT_ID/PATTERN/FIFTEEN_CHARACTERS*

However, if the first condition is met, i.e., the path consists of at least two levels of nesting, then it need not be 15 characters long.

3. The path is a complete file path:
   The path specified is a complete path pointing to a file, with the file extension present at the end of the path, as shown below:
   ✅ https://ik.imagekit.io/IMAGEKIT_ID/PATTERN/FILE.EXT*

For example, the path /sample.jpg* is valid despite not being 15 characters long or having two levels of nesting.

Purge has the following limitations:

• Based on your pricing plan, you can purge a limited number of URLs per month. After that, each cache purge request is charged as per your pricing plan.
• Note that the wildcard can only be appended at the end of a URL. Wildcards within the path are not supported. i.e., /folder/*/sample.jpg is an invalid path. Please reach out to us at support@imagekit.io if you need to purge all images on a specific pattern not supported through the API.

When using ImageKit behind your CDN, you must purge the cache on both ImageKit and your CDN in specific order to ensure that the resource is updated. With custom CDN integration, you probably use custom domain name integration and have mapped custom domains with ImageKit's URL endpoint.

Follow the steps to update a resource:

1. First, update the resource on your origin server.
2. Purge cache from ImageKit.
3. Verify that the resource is updated on ImageKit. Fetch the resource using the ImageKit URL endpoint to ensure that the resource is updated.
4. Once you have verified that the resource is updated on ImageKit, purge the cache on your CDN. This ensures that the resource is updated on your CDN as well.

We suggest you follow these best practices to ensure optimal performance and cost-effectiveness:

1. Do not rely on cache purging as a primary method to update resources. Instead, use versioning or query parameters to update resources. For example, you can use https://ik.imagekit.io/IMAGEKIT_ID/resource.jpg?v=2 and update the value of v query parameters to update the resource. Never add a value that changes on every request. When the query parameter updates, it is like a new URL for the browser or the app, and therefore it fetches the new resource from the server. This guarantees that your users always get the latest version of the resource.
2. Check your cache hit ratio in the ImageKit dashboard analytics to understand how effectively your resources are being cached. A high cache hit ratio above 80% indicates that your resources are being served from the cache with optimal performance.
3. Add transformation parameters in the query instead of path to allow for wildcard invalidation of all resources. For example, you can purge https://ik.imagekit.io/your_imagekit_id/resource.jpg/* to purge all transformations of resource.jpg. If you use transformations in the path, you must purge each transformation individually.