Real-Time Purge

Real-Time Purge removes a cached object from Cache, or from Tiered Cache, before its TTL ends, so the next request fetches the current version from the origin. A purge takes one of three arguments: a list of URLs, a list of cache keys, or one wildcard expression. Azion queues the purge after the confirmation and lists it in the purge history when it is complete. Use a purge to serve an update the origin already has, to remove an obsolete object, or to keep control of what Azion serves for dynamic content. For the steps, refer to Purge cached content. For the format of a key, refer to Cache keys.

Interfaces

Five interfaces send the same purge. Each one names the purge type, carries the argument list, and names the layer.

Interface	Purge
Azion Console	Real-Time Purge, where you choose the purge type and the layer and enter the argument list. For the steps, refer to Purge cached content
Azion API v4	`POST /v4/workspace/purge/{purge_type}`, with `purge_type` set to `url`, `cachekey`, or `wildcard`, and a body with `items` and `layer`
Azion CLI	`azion purge` with `--urls`, `--cachekey`, or `--wildcard`, and `--layer`
`azion.config.js`	An entry of the `purge` array, of type `AzionPurge`, with `type`, `items`, and `layer`
Azion Lib	`purgeURL`, `purgeCacheKey`, and `purgeWildCard` from `azion/purge`

The API authenticates with a personal token in the Authorization: Token <token> header. For more information, refer to Personal tokens.

Layers

A purge names the layer it clears. The layer field of the API body and the --layer flag of the CLI are optional, and both default to cache.

Layer	API value	What it purges
Cache	`cache`, the default	The objects cached on Azion’s distributed infrastructure
Tiered Cache	`tiered_cache`	The objects in the second cache layer, on applications whose cache setting has the module on; by cache key only. A URL or wildcard purge with this layer returns error `30001`

To purge an object from both layers, purge Tiered Cache first, then Cache, so the cache is not refilled from a stale Tiered Cache copy.

Purge types

The purge_type segment of the API path, the CLI flag, and the Console’s purge type name the same three types.

Type	`purge_type`	Argument	Per request	Layers
URL	`url`	A list of URLs	Up to 50	`cache`
Cache key	`cachekey`	A list of cache keys	Up to 50	`cache`, `tiered_cache`
Wildcard	`wildcard`	One wildcard expression	1	`cache`

URL purge

A URL purge takes a list of URLs and is not recursive: only the URLs in the list leave the cache. Azion converts each URL to its cache key with no content variation, so a variation by cookie, device group, or image format does not expire with it. Purge those variations with a cache key or a wildcard. A variation by query string is part of the URL, so it does expire when the arguments are in the same order as in the cache key. With Sort on in the cache setting, send the arguments in alphabetical order, or use a cache key or wildcard purge. For the Sort control, refer to Cache settings.

A URL is scheme://host or host, with an optional /path and ?query-string. Without a scheme, Azion purges both the HTTP and the HTTPS copies. An asterisk (*) in a URL purge is a literal character, not a wildcard. The list below carries four valid URL arguments:

http://www.example.com
http://static.example.com/include/site.css
https://static.example.com/include/site.js
dynamic.example.com/app.py?argument

Cache key purge

A cache key purge takes a list of cache keys. A key names one variation of an object. It can vary by query string, with or without Sort, by cookie, device group, or request method through Advanced Cache Key on Application Accelerator, or by image format through Image Processor. To purge every variation of an object, list every key. A cache key purge is the only type that reaches the Tiered Cache layer.

Wildcard purge

A wildcard purge takes one expression: scheme://host or host, with an optional /path and ?query-string, and an asterisk (*) in the path or in the query string. Several asterisks match a more complex path. Each request carries one expression, and a wildcard purge reaches the Cache layer only, not Tiered Cache. The list below carries ten valid wildcard expressions:

www.example.com/*
static.example.com/include/*.css
static.example.com/*/site.js
static.example.com/static/images/image_1.jpg?ims=*
www.example.com/alpha*
www.example.com/*beta*
www.example.com/*a*/charlie
www.example.com/*a*/*a*
www.example.com/*?b*
www.example.com/*?*2*c=*

Purge content that varies

When a cache setting varies the cache key, one object has one key per variation. The table names the purge that reaches each kind of variation.

Variation	How to purge
Cookies	A cache key purge that lists every variation, or a wildcard purge with `@@*` at the end
Query string	A cache key purge that lists every variation, a wildcard purge with `?` at the end, or a URL purge that names only the arguments in the key, in alphabetical order when Sort* is on
Device group	A cache key purge that lists every variation, or a wildcard purge
Image Processor	A cache key purge that lists every variation, or a wildcard purge with `*` at the end
Large File Optimization	A cache key purge that lists every fragment’s key, or a wildcard purge such as `static.example.com/media/file.mp4*`
Cached `POST` and `OPTIONS`	A cache key purge that lists every variation, or a wildcard purge with `@@*` at the end

Query-string, cookie, device group, and request method variation come from Advanced Cache Key, a feature of Application Accelerator. The same module caches POST and OPTIONS responses; without it, Azion caches GET and HEAD only. For the behaviors, refer to Application Accelerator settings.

An image that Image Processor serves has one key per processing and per format. The key carries the host and path, the processing arguments after the ? separator, and the format after @@. The four keys below belong to one image:

httpstatic.example.com/static/images/image.jpg@@
httpstatic.example.com/static/images/image.jpg@@webp
httpstatic.example.com/static/images/image.jpg?ims=88x@@
httpstatic.example.com/static/images/image.jpg?ims=88x@@webp

With Large file optimization on, Azion caches a large object in fragments, each with its own key. The file can stay in the cache after a purge of its URL. To purge it, list each fragment’s key, or use the wildcard static.example.com/media/file.mp4*, which clears every fragment of one file.

A purge of individual fragments can leave old and new fragments side by side. When the file changes at the origin, a fragment that was not purged stays in the cache next to the fragments fetched again.

Request body

The API reads the purge type from the path and the arguments from items. The request body below sends a URL purge through POST /v4/workspace/purge/url:

{"items":["https://www.example.com/include/site.js"],"layer":"cache"}

A wildcard purge goes through POST /v4/workspace/purge/wildcard; without layer, the API purges cache:

{"items":["www.example.com/include/*.css"]}

A cache key purge goes through POST /v4/workspace/purge/cachekey:

{"items":["httpswww.example.com/include/site.js"],"layer":"cache"}

Each request answers with HTTP 201, state set to executed, and the items and the layer under data:

{"state":"executed","data":{"items":[...],"layer":"cache"}}

The CLI sends the same three purges from the command line, the last one to the Tiered Cache layer:

Shell

01azion purge --urls "https://www.example.com/include/site.js"

02azion purge --wildcard "www.example.com/include/*.css"

03azion purge --cachekey "httpswww.example.com/include/site.js" --layer tiered_cache

Each command prints one line:

Purge carried out successfully

After the purge, the next request for the object returns x-cache: MISS, because Azion fetches it from the origin again.

Confirmation

After you create a purge, a message confirms the creation. Azion then queues the purge, and it appears in the purge history when it is complete, because the result takes time to propagate across Azion’s distributed infrastructure. The history can be filtered by the user who made the purge, the time, the argument list, the purge type, and the method.

Errors

The API answers each request below with HTTP 400. The body carries the code, the title, and a detail.

Code	Title	Cause	What to do
`30001`	`Invalid Purge Layer For Purge Type`	`layer` is `tiered_cache` on a `url` or `wildcard` purge; the detail reads `Invalid purge layer for purge type "url".`	Purge Tiered Cache by cache key, or set `layer` to `cache`.
`30003`	`Unauthorized Domain`	An item names a domain the account does not own; the detail reads `The domain is not authorized for your account.`	Correct the domain in the item. A purge reaches only the domains the account owns.
`30005`	`Invalid Purge Cachekey`	An item of a `cachekey` purge is not a valid cache key; the detail reads `The Content must be a valid cachekey.`	Send the key as the `x-cache-key` header shows it; the format is on Cache keys.
`10065`	`List Field Max Length`	`items` has more than 50 elements on a `url` or `cachekey` purge, with the detail `Ensure this field has no more than 50 elements.`; or more than 1 element on a `wildcard` purge, with the detail `Ensure this field has no more than 1 elements.` and `meta.max_length` set to `1`.	Split the list into requests of 50 items or fewer, and send one wildcard expression per request.

Limits

The bounds below apply to purge requests. Each row names the API’s answer past the value where a source states one.

Value	Bound	Past the bound
URL or cache key length	4,096 characters	No error is documented
URL and cache key requests per client	200 requests, 50 objects per request	HTTP `400`, error `10065` above 50 objects in one request
URL and cache key objects per minute	10,000 objects every 60 seconds	No error is documented
Wildcard requests per day	2,000 requests in a 24-hour interval	No error is documented
Wildcard expression length	256 characters	No error is documented
Wildcard expressions per request	1	HTTP `400`, error `10065`
Purge history	1,000,000 requests	No error is documented
Purge history retention	6 months	No error is documented

For the purges each plan includes, refer to Applications limits.

Purge cached content

The Console, API, and CLI steps that send a URL, cache key, or wildcard purge.

Tiered Cache

The second cache layer that a cache key purge clears.

Expiration and freshness

What the TTL and stale cache do to a request, and what a purge changes.

Applications best practices

Versioned object names as the alternative to purging.