Vercel’s cache-tag purge API lets teams invalidate cached CDN, Runtime, and Data responses at runtime without cutting a new deployment. The purge invalidates stale content; it does not make the revalidation free. Pick the wrong verb and a single call can force foreground origin fetches across a hot tag, which is why dangerously-delete carries the name it does.
What Vercel’s purge API actually invalidates
As of 2026-06-23, Vercel’s purge API invalidates cached responses by cache tag, a surrogate key you attach to a response, rather than by URL path or header pattern. The CDN cache’s own keys are not user-configurable, so the only unit of selective invalidation is a tag you assign at response time through the Vercel-Cache-Tag header, addCacheTag() from @vercel/functions, or cacheTag() from next/cache. Once a response carries a tag, purging it clears all three cache layers at once: the CDN cache, the Runtime Cache, and the Data Cache, according to the purge reference.
That all-at-once clearing is the design choice that matters. A layer-aware purge could leave the CDN refreshed while the Data Cache lags, one tier visibly stale as the other updates. Vercel’s model avoids that split by treating the tag as a single key across layers. The trade is that you cannot purge just one layer, which is reasonable given that partial invalidation is usually the source of cache-coherence bugs.
The tagging scheme is where the model earns its keep or breaks. Tags are typically derived from the entities a response depends on (a product ID, an author handle, a taxonomy term), so a single update to one entity can invalidate every page that renders it without enumerating URLs. The scheme has to be designed up front: responses tagged loosely over-purge, and responses tagged too narrowly under-purge and serve stale data.
Because the unit of invalidation is the tag, not the path, you pay the tagging cost once at build time and reclaim the ability to invalidate by entity later. Path-based invalidation, by contrast, requires enumerating every URL that changed, which is usually impractical for anything user-generated.
Invalidate vs dangerously-delete: the verb that decides origin load
As the docs describe it (accessed 2026-06-23), invalidate keeps serving the cached response while it revalidates in the background, so end users see no added latency; dangerously-delete forces a foreground MISS that can stampede the origin when the tag covers many objects. The CLI makes the two states explicit: vercel cache invalidate serves STALE and revalidates in the background, while vercel cache dangerously-delete serves a MISS and blocks on revalidation. The same pair of states applies across the other interfaces. (The distinction is the one operators already know from Fastly’s surrogate-key soft purge.)
The naming is unusually honest about the trade-off. There is no “safe” flag that makes delete throttle itself; the safety lives entirely in choosing invalidate instead, and in scoping the tag set so a single call cannot fan out across the whole cache.
The tagging surface and the CLI purge
The purge model has two halves: the tags you attach at response time, and the commands that invalidate them. The cached references document three ways to attach a tag, and the CLI as the purge surface that fires by tag or by source image.
| Surface | Confirmed mechanisms |
|---|---|
| Tagging (response time) | Vercel-Cache-Tag response header; addCacheTag() from @vercel/functions; cacheTag() from next/cache |
| Vercel CLI purge | vercel cache invalidate, vercel cache dangerously-delete (both accept --tag or --srcimg); vercel cache purge clears CDN and Data cache for the current project |
The CLI additionally offers --revalidation-deadline-seconds, which narrows a delete to entries not accessed within the given window, so you can expire a cold long tail without disturbing recently served objects. That is the closest thing to a built-in brake on a stampede, and it only applies to the delete path.
Tags are bounded by length and count limits worth keeping next to a runbook; the purge reference documents the exact ceilings.
Purge vs redeploy: why they aren’t interchangeable
A redeploy ships new code and creates a new deployment with its own cache key; a purge clears cached responses for an existing deployment. They solve different problems. Each deployment carries its own cache key, so promoting a new deployment to production does not touch the previous deployment’s cache. A purge clears all three cache layers (CDN, Runtime, and Data) for the deployment it targets, per the purge reference; a redeploy, by contrast, simply points production at a fresh deployment.
The per-deployment isolation also means a purge targets one deployment, not every deployment built from the same code, so production and preview caches stay independent under normal scoping. The practical split follows from that. When the defect is in your data rather than your code, a purge is the cheaper fix and you keep your current deployment. When the defect is in your code, no amount of purging corrects it; a redeploy is the only real remedy, and reaching for a purge to “fix” a rendering bug just regenerates the same wrong output from the same code.
Where purge fits relative to ISR and Cache-Control headers
Three invalidation models sit on the same origin, and purge is the runtime escape hatch among them. Cache-Control headers tell the CDN how long to keep a response, but the CDN only learns a path is cacheable after the first response is served. ISR inverts that: Vercel knows a path is cacheable before the first request arrives, which enables request collapsing and durable storage that Cache-Control alone cannot provide. ISR cache is scoped per-deployment, persists for 31 days or until revalidated, and reaches all CDN regions within 300ms on an on-demand revalidation.
For practitioners, the decision is which model to make authoritative. Rely on Cache-Control and you get a portable TTL with no collapsing. Rely on ISR and you get request collapsing and durable storage in exchange for coupling your invalidation to the framework. Reach for a runtime purge when both of the above have served something you need gone immediately.
ISR revalidation primitives live in application code and fire on a content change; the CLI purge commands are operational tools a human or runbook triggers to correct something now, without a deploy. The two overlap in capability but serve different callers.
Scoping keeps a purge from being blunt. Each deployment carries its own cache key, so a purge targets the deployment where it is triggered and does not bleed into other deployments’ caches, and tags are scoped per project and environment. That isolation is what makes a runtime purge safe to wire into automation: a misfired call cannot leak across deployments even when it clears more than you intended within one.
The broader shift is from build-time cache control to runtime cache control. That is a capability win for content and ops teams, who no longer need a deploy to drop a stale page, but it relocates the burden of correctness: whoever holds the purge trigger now owns origin load.
Frequently Asked Questions
Does Vercel charge for the purge call itself?
The purge event is not billed, but a delete on a hot tag surfaces elsewhere: Active CPU, Provisioned Memory, Function Invocations, Fast Origin Transfer, Image Optimization Transformations, Image Optimization Cache Writes, and ISR Writes all climb while the cache refills.
What are the numeric limits on a cache tagging scheme?
Tags cap at 256 characters each, 128 tags per cached response, and 16 tags per bulk REST call. A literal wildcard asterisk purges the entire project, which is the one fat-finger case to block at the automation layer.
Which purge paths exist besides the Vercel CLI?
Four surfaces: next/cache exposes revalidatePath, revalidateTag, and updateTag inside app code; @vercel/functions exposes invalidateByTag and dangerouslyDeleteByTag at the edge; the REST API exposes /invalidate-by-tag and /dangerously-delete-by-tag plus source-image variants; and the CLI. All four converge on the same tag-keyed invalidation.
Will a production purge clear preview or subdomain caches?
No. Each deployment carries its own cache key, and on-demand revalidation reaches only the domain and deployment where it is triggered, not subdomains or sibling deployments built from the same code. Production and preview caches stay isolated under normal scoping.
What does a purge clear that a redeploy leaves intact?
A redeploy points production at a new deployment and leaves Image Optimization and ISR content from the prior deployment in place. A purge clears those as well, which makes it the right tool for correcting a cached optimized image or a stale ISR page without shipping new code.
