# Purge Cloudflare Cache (`cloudflare.purge_cache`)

Clears cached content of one of your Cloudflare zones: everything, or by URLs, host names, cache tags or URL prefixes.

Docs: https://primaryapi.com/docs/api-reference/cloudflare/purge_cache

- Endpoint: `POST https://api.primaryapi.com/v1/run/cloudflare.purge_cache`
- Category: Web Scraping · Platform: `cloudflare` · Kind: lookup · Status: live
- Price: 1 credit per call. Every call costs the same, including calls that were retried automatically.
- Billing unit: per successful call
- Reliability: routed to a healthy upstream and retried automatically when an attempt fails; live 30-day status: `GET https://api.primaryapi.com/v1/status/apis?sku=cloudflare.purge_cache`
- Execution: synchronous (answers 202 only if it outlives the wait window)

## Input

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `zone` | string | yes |  | max 253 chars | The zone (domain) on Cloudflare: its domain name, for example "example.com", or its 32-character zone id from cloudflare.zones. |
| `everything` | true | no |  |  | true = purge everything cached for the zone. Heavy: every visitor request goes to your origin until the cache refills. Use it alone. |
| `urls` | string[] | no |  | min 1 items; max 100 items; items max 2048 chars | Full URLs to purge, for example "https://www.example.com/css/styles.css" (1-100; no wildcards). UTF-8; the path is case-sensitive. |
| `hosts` | string[] | no |  | min 1 items; max 100 items; items max 2048 chars | Host names whose cached content to purge, for example "images.example.com" (1-100). |
| `tags` | string[] | no |  | min 1 items; max 100 items; items max 2048 chars | Cache-Tag values whose content to purge (1-100; up to 1,024 characters each, no spaces; case-insensitive). |
| `prefixes` | string[] | no |  | min 1 items; max 100 items; items max 2048 chars | URL prefixes without scheme, for example "www.example.com/blog/" (1-100; no query string or fragment; at most 31 "/"). |
| `connection` | string | no |  | max 200 chars | Which connected account to use when the workspace has several for this provider: the customId you gave it (exact), its connection id ("con_…"), its handle (login, email or @handle) or its name. Optional; prefer the customId or id, which never match two accounts. |

Unknown fields are rejected with `400 invalid_input`. The routing controls `preferLatencyUnderMs` and `maxCredits` may be sent in the same JSON body.

## Output

When `output.found` is `true`, `output.data` has this shape:

| Field | Type | Description |
|---|---|---|
| `zoneId` | string | Cloudflare zone id |
| `zone` | string | The zone’s domain name |
| `purged` | enum | What was purged |
| `count` | integer | Items sent (0 for everything) |
| `accepted` | boolean | Cloudflare accepted the request. False when it refused some items (see errors); nothing is confirmed either way |
| `purgeId` | string \| null | Cloudflare’s id of the purge request |
| `errors` | object[] | Items Cloudflare refused |
| `errors[].code` | integer |  |
| `errors[].message` | string |  |

When the thing you asked about does not exist (or a search matches nothing) the call still succeeds: `output.found` is `false`, `output.data` is `null` and `output.reason` says why (`not_found`, `private`, `no_results`, …). Misses are free unless the notes below say misses are billed.

## Example request

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/run/cloudflare.purge_cache" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"zone":"example.com","urls":["https://www.example.com/css/styles.css","https://www.example.com/js/index.js"]}'
```

## Example response

_Values are placeholders that follow the output schema; `credits` is what this call would cost at the usual price._

```json
{
  "output": {
    "found": true,
    "data": {
      "zoneId": "023e105f4ecef8ad9ca31a8372d0c353",
      "zone": "example.com",
      "purged": "urls",
      "count": 2,
      "accepted": true,
      "purgeId": "023e105f4ecef8ad9ca31a8372d0c353",
      "errors": []
    }
  },
  "provider": "PrimaryAPI",
  "credits": 1,
  "items": 1,
  "requestId": "req_01JBXK6Y2N9V8T4R3Q2P1M0A7Z"
}
```

## Pricing and reliability

- Usual price: 1 credit per call
- Price ceiling: the usual price, even when a call is retried. A quote’s `maxCredits` is the most a given call can cost; the `maxCredits` routing control caps it per call
- Live 30-day status, success rate, uptime and latency: `GET https://api.primaryapi.com/v1/status/apis?sku=cloudflare.purge_cache`

## Errors to handle

`invalid_input`, `unauthorized`, `insufficient_balance`, `key_limit_reached`, `trial_cap_reached`, `forbidden`, `not_found`, `idempotency_conflict`, `rate_limited`, `all_sources_failed`, `service_unavailable`, `timeout`. See https://primaryapi.com/docs/errors.

## Notes

Runs as your connected Cloudflare account and needs the "Purge cache" permission. Purging changes what your live site serves: the next request for purged content goes to your origin, and Cloudflare does not serve purged content again even if the origin is down. Prefer URLs, tags, hosts or prefixes over everything. Every URL, host and prefix must belong to the zone. Accepted means Cloudflare took the request, not that anything was cached. Purge rate limits are per Cloudflare account and depend on its plan (the Free plan allows 5 host, tag, prefix or everything purges per minute); a limit comes back as rate_limited (with retryAfterSeconds when Cloudflare sends one). Not retried automatically; results are never stored.

