cache/purgeByTag

Purge all cached assets associated with specific Cache-Tag values. Enterprise plan required.

Enterprise plan required: Cache tag purging requires a Cloudflare Enterprise plan. Additionally, your origin server must set Cache-Tag response headers on cacheable responses. Tags are ignored on non-Enterprise zones.

When to Use

Product image invalidation: Tag all product images with product-images-{productId} and purge that tag when the product is updated — invalidates all image variants, sizes, and formats at once.
Category page invalidation: Tag all pages in a category with category-{categoryId}. Purge the tag when the category is updated to clear all related pages without knowing each URL.
User-specific cache: Tag user-specific responses with user-{userId} and purge that tag when the user's profile data changes.
CMS taxonomy update: After updating a shared taxonomy term (e.g., a tag or author), purge the corresponding cache tag to invalidate all content that uses it.

How Cache Tags Work

Your origin server must include the Cache-Tag response header on each cacheable response. Cloudflare stores the tags alongside the cached content. When you purge a tag, all cached assets that were served with that tag are invalidated across all Cloudflare edge nodes.

Example origin response header: Cache-Tag: product-123, category-electronics, brand-acme

Configuration

Connection

Field	Type	Required	Description
`ApiToken`	string	required	Scoped Cloudflare API Token with `Cache Purge` permission. Store in BizFirst Credentials Manager.

Operation Fields

Field	Type	Required	Description
`ZoneId`	string	required	32-character hexadecimal Zone ID. Zone must be on Enterprise plan.
`Tags`	array	required	Array of cache tag strings to purge. Example: `["product-123", "category-electronics"]`.

Sample Configuration

{
  "resource": "cache",
  "operation": "purgeByTag",
  "connection": {
    "ApiToken": "{{ $credentials.cloudflare_cache_purge }}"
  },
  "ZoneId": "023e105f4ecef8ad9ca31a8372d0c353",
  "Tags": [
    "product-456",
    "category-widgets"
  ]
}

Validation Errors

Code	Condition	Resolution
`MISSING_API_TOKEN`	ApiToken is empty	Set the ApiToken credential with Cache Purge permission
`MISSING_ZONE_ID`	ZoneId is empty	Provide the Zone ID
`UNKNOWN_ERROR`	Zone is not Enterprise, or tags are invalid	Verify the zone is on Enterprise plan; confirm origin sets Cache-Tag headers

Output

Success Port

Field	Type	Description
`id`	string	Purge job ID assigned by Cloudflare — log for audit trail
`status`	string	`ok` when the purge request was accepted

Error Port

On failure, the error port receives an object with code and message.

Sample Output

{
  "id": "4f5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d",
  "status": "ok"
}

Expression Reference

Expression	Returns
`{{ $node.PurgeByTag.output.id }}`	Purge job ID for audit log
`{{ $node.PurgeByTag.output.status }}`	"ok" on success

Node Policies & GuardRails

Policy	Detail
Verify Enterprise plan before use	Call zone/get upstream and confirm `plan.name === "Enterprise"` — cache tag purging silently fails on lower plans
Coordinate tag naming with origin team	Tags must match exactly what the origin sets in the Cache-Tag header — establish a naming convention across teams
Use Cache Purge scoped token	Token needs only Cache Purge permission — do not use a broader token
Store ApiToken in Credentials Manager	Never hardcode the token in configuration JSON
Log purge job IDs with tag names	Record both the purge ID and the tags that were purged for incident investigation and audit

Examples

Example 1: Product Update Cache Invalidation

When a product record is updated in the database: (1) Build the tag: "product-{productId}". (2) Call cache/purgeByTag with that tag. All pages, images, and API responses tagged with this product ID are instantly invalidated across all edge nodes without needing to know each individual URL.

Example 2: Author Bio Update

When an author updates their bio in the CMS: (1) Build the tag: "author-{authorId}". (2) Call cache/purgeByTag. All articles, list pages, and sidebars that include the author's bio (and were tagged with the author ID by the origin) are purged in one call.

Example 3: Staged Cache Invalidation by Feature Flag

After a feature flag is toggled that affects a set of pages: (1) Build tags for each affected feature: ["feature-checkout-v2", "feature-promo-banner"]. (2) Call cache/purgeByTag with all relevant tags. (3) Log the purge event with feature flag name, purge job ID, and timestamp.