# Real-Time Purge **Real-Time Purge** removes a cached object from [Cache](/en/documentation/platform/applications/#cache), or from [Tiered Cache](/en/documentation/platform/applications/cache/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](/en/documentation/guides/application-performance/cache-and-purge/purge-cached-content/). For the format of a key, refer to [Cache keys](/en/documentation/platform/applications/cache/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](https://console.azion.com/) | **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](/en/documentation/guides/application-performance/cache-and-purge/purge-cached-content/) | | [Azion API v4](/en/documentation/devtools/api/) | `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`](/en/documentation/devtools/cli/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](/en/documentation/devtools/azion-lib/purge/) | `purgeURL`, `purgeCacheKey`, and `purgeWildCard` from `azion/purge` | The API authenticates with a personal token in the `Authorization: Token ` header. For more information, refer to [Personal tokens](/en/documentation/guides/platform/account-and-billing/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](/en/documentation/platform/applications/cache/cache-settings/#application-accelerator). 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](/en/documentation/platform/applications/#application-accelerator), or by image format through [Image Processor](/en/documentation/platform/applications/#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](/en/documentation/platform/applications/#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](/en/documentation/platform/applications/application-accelerator/settings/). An image that [Image Processor](/en/documentation/platform/applications/#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. > **Caution** > > 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`: ```json {"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`: ```json {"items":["www.example.com/include/*.css"]} ``` A cache key purge goes through `POST /v4/workspace/purge/cachekey`: ```json {"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`: ```json {"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: ```bash azion purge --urls "https://www.example.com/include/site.js" azion purge --wildcard "www.example.com/include/*.css" azion purge --cachekey "httpswww.example.com/include/site.js" --layer tiered_cache ``` Each command prints one line: ```text 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](/en/documentation/platform/applications/cache/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](/en/documentation/platform/applications/limits/#cache). --- ## Related resources - [Purge cached content](/en/documentation/guides/application-performance/cache-and-purge/purge-cached-content.md): The Console, API, and CLI steps that send a URL, cache key, or wildcard purge. - [Tiered Cache](/en/documentation/platform/applications/cache/tiered-cache.md): The second cache layer that a cache key purge clears. - [Expiration and freshness](/en/documentation/platform/applications/cache/expiration-and-freshness.md): What the TTL and stale cache do to a request, and what a purge changes. - [Applications best practices](/en/documentation/platform/applications/best-practices.md#cache): Versioned object names as the alternative to purging.