Purges in the portal

Purges is where you throw cached responses away by hand and see every purge that has happened, automatic or manual. Open a service in the portal and choose Purges. What a purge is, and which key to reach for, is in invalidation; the same purges from a script are in purging through the API and CLI.

Permission cache:purge

A service that is not serving yet shows a short panel instead: with nothing built, there is nothing to purge.

Who can purge

Every purge needs the cache:purge permission. service:edit does not include it. Without it:

the Purge button at the top of the Purges page stays visible but is disabled, and says why when you point at it;
every other purge control in the portal (in the Insights request detail and beside the keys on the Schema pages) is not shown at all.

The page is the exception to the portal’s hidden or disabled rule: a page called Purges without its button would look broken. Reading the history needs only service:view. See permissions.

Purge by key or hash

Select Purge at the top of the page. The Purge cache dialog opens.
Under Kind, choose Hard (“Dropped now. The next request waits for your origin.”) or Soft (“Served while it refreshes, so nobody waits.”). A soft purge marks entries stale rather than removing them; see soft and hard.
Under What to purge, enter what to invalidate. The field takes surrogate keys and query hashes, one or many:
- Type a key and press Enter, a comma or a space to add it. Keys cannot contain spaces, so a space always ends one.
- Paste a list. Pasted text is split on spaces, commas and line breaks, and each part is added on its own.
- Pick a key pattern. As you type, the field suggests the keys your live schema declares, with the type each belongs to. A pattern with parts, such as User:id:{id}, opens as a line to fill in: type each part, move between them with Tab, and press Enter to add the key. The pattern stays loaded, so the next key of the same shape is one value away.
- Reuse a recent key. The clock button in the field lists keys you purged before from this browser (the last 20 per service). While you type, up to three of them are suggested alongside the patterns.
Each entry becomes a chip marked key or operation. A value of exactly 64 hexadecimal characters is read as a query hash (an operation); anything else is a surrogate key. A query hash purges the operation with every variable set. To purge a single cached response by its cache key, enter the key with its ck: prefix; see purging one cached response by its cache key.
Select the button, which names what you entered (for example Purge 3 keys or Purge 1 operation). Nothing is sent yet.
Purge this cache? lists every key or hash, with whether it is a hard or a soft purge. Select Yes, purge immediately (hard) or Yes, mark stale (soft), or Back to change it.

The dialog refuses these before you send them:

keys and query hashes in the same purge (purge them separately),
more keys than one purge may name,
a key with a space or a character outside printable ASCII, such as a non-ASCII letter. The portal accepts only printable ASCII keys without spaces; to purge another key, use the API or the CLI.

The limits are on limits.

When it is done, Purged says what was invalidated and lists the keys. The count is a count of keys, not of cached responses: a key with nothing cached behind it still counts. The purge takes effect immediately; it can take up to a minute to appear in the history.

Purge all

Purge all, in the other corner of the Purge cache dialog, empties the service’s whole cache. Until the cache fills again, every request reaches your origin.

Select Purge, then Purge all.
Purge everything? asks you to type the service’s slug (its subdomain) to confirm.
Select Yes, purge everything.

A purge-all is always hard. It cannot be undone and cannot be aimed at part of the cache.

Purging from other pages

Where the portal already shows what to purge, it offers the purge there. The same dialog opens, on its confirmation step when the target is complete:

Insights, in a request’s detail panel: Purge this request, the cache key, each surrogate key, and the operation with or without its variables. See the request detail panel.
Schema, wherever a surrogate key is listed (the Surrogate keys view, a type in the Explorer, an operation). A key with parts, such as User:id:{id}, opens the Purge cache dialog with its pattern loaded, ready to fill in. See findings.

The purge history

The list shows the purges in the time range picked at the top of the page (the last 24 hours by default), newest first. It is built from request telemetry, so it follows the same storage and retention rules; see what Insights needs. An Admin can delete it with reset history.

Column	Shows
When	The time of the purge.
Trigger	Automatic for a purge a write’s response caused, Manual for one somebody sent.
Scope	The first key and how many more (`User:id:1 and 2 more`), or Entire cache for a purge-all.
Outcome	What was done, for example Invalidated 3 keys or Marked 2 keys stale. A purge that recorded an error reads Unclear what was invalidated.
Actor	The member who sent a manual purge. Empty for an automatic purge, and for a purge sent with an API key.

The refresh button beside the time range reloads the list.

Filters

The filter panel beside the list narrows it down:

Filter	Keeps
Trigger	Automatic or Manual purges.
Scope	Purge all (the whole cache) or Keys (keyed purges).
Kind	Soft or Hard purges.
Outcome	Only purges marked Unclear what was invalidated.
Key	Purges with at least one key containing this text, matched literally.

Reset all filters clears them.

One purge

Select a row to open the purge. The detail panel lists every key it addressed and, depending on the purge:

Triggered by: for an automatic purge, the request that caused it, linked to its request detail. Once that request is older than your telemetry retention, the panel says so instead.
Addressed request: for a manual purge sent with purgeByRequest, the request it named.
Requested by: for a manual purge sent by a signed-in member, that member.
Outcome: when the purge recorded an error, Unclear what was invalidated and a note to send the purge again.

What each record means, what an automatic purge records, and how to check at the edge that a response is gone are on verifying a purge.