• The request method (such as GET, POST, etc)
• The request URL (query strings are ignored for static files)
• The host domain
• The unique deployment URL
• The scheme (whether it's https or http)

Since each deployment has a different cache key, you can promote a new deployment to production without affecting the cache of the previous deployment.

static images and remote images.

Cache keys are not configurable. To purge the cache you must configure cache tags.

Understanding cache purging

When you purge by cache tag, Vercel purges all three types of cache: CDN cache, Runtime Cache, and Data Cache. This ensures your content updates consistently across all layers.

Invalidating the cache

When you invalidate a cache tag, all cached content associated with that tag is marked as stale. The next request serves the stale content instantly while revalidation happens in the background. This approach has no latency impact for users while ensuring content gets updated.

Deleting the cache

When you delete a cache tag, the cached entries are marked for deletion. The next request fetches content from your origin before responding to the user. This can slow down the first request after deletion. If many users request the same deleted content simultaneously, it can create a cache stampede where multiple requests hit your origin at once.

Cache tags

Cache tags (sometimes called surrogate keys) are user-defined strings that can be assigned to cached responses. These tags can later be used to purge the CDN cache.

For example, you may have a product with id 123 that is displayed on multiple pages such as /products/123/overview, /products/123/reviews, etc. If you add a unique cache tag to those pages, such as product123, you can invalidate that tag when the content of the product changes. You may want to add another tag products to invalidate all products at once.

There are several ways to add cache tags to a response:

• Vercel-Cache-Tag response header: Set the Vercel-Cache-Tag header on responses from Vercel Functions or external rewrites. The value is a comma-separated list of tags.
• addCacheTag() function: Import addCacheTag from @vercel/functions and pass in your tag.
• cacheTag() function (Next.js only): Import cacheTag from next/cache and pass in your tag.

The example below sets both Vercel-CDN-Cache-Control and Vercel-Cache-Tag in a Vercel Function to ensure the response is cached and can be purged on-demand by tag at some point in the future:

Vercel's CDN can also cache and purge responses originating outside of Vercel by using external rewrites with the same headers.

Functions using ISR don't have access to the raw Response headers. You can add cache tags by importing addCacheTag from @vercel/functions to add tags at runtime.

If you're using Next.js, you can add cache tags by importing cacheTag from next/cache instead.

Cache tag case sensitivity

Cache tags are case-sensitive, meaning product and Product are treated as different tags.

Cache tag allowed characters

Cache tags must not contain commas. The comma character ( ,) is reserved as a delimiter in the Vercel-Cache-Tag header and in API calls that accept multiple tags. If a tag contains a comma, it's interpreted as two separate tags.

Cache tag scope

Cache tags are scoped to your project and environment (production or preview).

When you purge a tag with the REST API, you can optionally provide a target environment such as preview or production (default is all environments).

When you purge a tag using @vercel/functions at runtime, the function's current environment is used which is derived from the deployment url that invoked the function.

When using rewrites from a parent project to a child project and both are on the same team, cached responses on the parent project will also include the corresponding tags from the child project.

System cache tags

Vercel's CDN automatically adds system cache tags to certain cached responses so you can easily purge by tag at your convenience.

For example, a cached response from Image Optimization automatically adds the source image as a cache tag to each transformed image. These may contain commas, unlike user-defined cache tags.

This allows you to purge by a single source image without purging the entire project.

Programmatically purging CDN Cache

You can purge Vercel CDN cache in any of the following ways:

• next/cache: Use helper methods like revalidatePath(), revalidateTag(), or updateTag()
• @vercel/functions: Use helper methods like invalidateByTag(), dangerouslyDeleteByTag(), invalidateBySrcImage(), or dangerouslyDeleteBySrcImage()
• Vercel CLI: Use the vercel cache invalidate command or vercel cache dangerously-delete command with --tag or --srcimg options
• REST API: Make direct API calls to the edge cache endpoint like /invalidate-by-tag, /dangerously-delete-by-tag, /invalidate-by-source-image, or /dangerously-delete-by-source-image

Manually purging Vercel CDN Cache

In some circumstances, you may need to purge cached responses and force revalidation. For example, you might set a Cache-Control value that caches a response for a month, then update the content before that month ends. You can purge the cache from the dashboard:

1. Under your project, open CDN in the sidebar, then select Caches.
2. In the Purge cache section, choose what you want to purge.
3. Click Purge.
4. In the dialog, you'll see two options:
   • Invalidate: Marks a cache tag as stale, causing cache entries associated with that tag to be revalidated in the background on the next request. This is the recommended method for most use cases.
   • Delete: Marks a cache tag as deleted, causing cache entries associated with that tag to be revalidated in the foreground on the next request. Use this method with caution because one tag can be associated with many paths and deleting the cache can cause many concurrent requests to the origin leading to cache stampede problem. This option is for advanced use cases and is not recommended; prefer using Invalidate instead.
5. In the dialog, you'll see a dropdown with two options:
   • Cache Tag: Purge cached responses associated with a specific user-defined tag.
   • Source Image: Purge Image Optimization transformed images based on the original source image URL.
6. In the dialog, enter a tag or source image in the input. You can use * to purge the entire project.
7. Finally, click the Purge button in the dialog to confirm.