Purging

A purge removes one file, given as its full URL on one of the zone's hostnames, or everything the zone has cached, from every location within about five seconds, and the next request for it is fetched from your origin. From the API both are one call: see Purging in the API reference.

What a file purge matches#

• The exact path and query string. /intro.mp4 and /intro.mp4?v=1 are two files, and purging one leaves the other. There is no wildcard and no purge by prefix or folder; for that, purge the zone.
• Every hostname of the zone at once, whether they share one copy or hold one each.
• Every compressed and uncompressed copy, and every piece of a large file.
• The scheme and the port in the URL do not matter. The hostname has to be one of the zone's own, or the purge is refused, and the URL is at most 2,048 characters.

How fast#

The zone page shows the purge landing as a bar that fills by itself and then reads Purged everywhere; the API reports the same as APPLIED_NODES, ONLINE_NODES and COMPLETE. A location that is offline applies the purge as soon as it comes back, before it serves anything. On a zone with a Home PoP, a location that applies the purge first can re-fetch the old copy from the Home PoP in the seconds before the Home PoP applies it too, and that copy then lives out its full lifetime; if a busy file has to be gone everywhere, purge it once more once the first purge reads complete.

Purging less#

The next request after a purge is a MISS, stored again under the lifetime your origin gives it or the zone's Cache Expiration Time; a purge does not touch your origin and does not pre-fetch anything. Two things make most purges unnecessary. A file whose name or query string changes with each version, app.3f9c.css or intro.mp4?v=2, is a new file to the cache the moment you deploy it, and the old one expires on its own. And a short lifetime on files you replace in place, from a max-age or from the zone's Cache Expiration Time, bounds how stale they can be without any purge: a bound rather than a promise, because an expired copy may still be served for up to 24 hours while the refresh behind it runs. Purges are free. The API's rate limit is the only limit on them, and the cost of one is that the next viewers of a busy file are served from your origin, one fetch per location rather than one per viewer.