TheCache API ↗ allows fine grained control of reading and writing from theCloudflare global network ↗ cache.

The Cache API is available globally but the contents of the cache do not replicate outside of the originating data center. AGET /users response can be cached in the originating data center, but will not exist in another data center unless it has been explicitly created.

Workers deployed to custom domains have access to functionalcache operations. So doPages functions, whether attached to custom domains or*.pages.dev domains.

However, any Cache API operations in the Cloudflare Workers dashboard editor andPlayground previews will have no impact. For Workers fronted byCloudflare Access ↗, the Cache API is not currently available.

Thecaches.default API is strongly influenced by the web browsers’ Cache API, but there are some important differences. For instance, Cloudflare Workers runtime exposes a single global cache object.

letcache=caches.default;
awaitcache.match(request);

You may create and manage additional Cache instances via thecaches.open ↗ method.

letmyCache=awaitcaches.open('custom:cache');
awaitmyCache.match(request);

// recommended approach: use your Worker hostname to ensure efficient caching
request.url="https://your-Worker-hostname.com/";
letmyCache=awaitcaches.open('custom:cache');
letresponse=awaitmyCache.match(request);

Our implementation of the Cache API respects the following HTTP headers on the response passed toput():

• Cache-Control
  • Controls caching directives. This is consistent withCloudflare Cache-Control Directives. Refer toEdge TTL for a list of HTTP response codes and their TTL whenCache-Control directives are not present.
• Cache-Tag
  • Allows resource purging by tag(s) later.
• ETag
  • Allowscache.match() to evaluate conditional requests withIf-None-Match.
• Expires string
  • A string that specifies when the resource becomes invalid.
• Last-Modified
  • Allowscache.match() to evaluate conditional requests withIf-Modified-Since.

This differs from the web browser Cache API as they do not honor any headers on the request or response.

cache.put(request,response);

• put(request, response) : Promise

  • Attempts to add a response to the cache, using the given request as the key. Returns a promise that resolves toundefined regardless of whether the cache successfully stored the response.

• request string | Request

  • Either a string or aRequest object to serve as the key. If a string is passed, it is interpreted as the URL for a new Request object.

• response Response

  • AResponse object to store under the given key.

cache.put will throw an error if:

• Therequest passed is a method other thanGET.
• Theresponse passed has astatus of206 Partial Content ↗.
• Theresponse passed contains the headerVary: *. The value of theVary header is an asterisk (*). Refer to theCache API specification ↗ for more information.

cache.put returns a413 error ifCache-Control instructs not to cache or if the response is too large.

cache.match(request,options);

• match(request, options) : Promise<Response | undefined>

  • Returns a promise wrapping the response object keyed to that request.

• request string | Request

  • The string orRequest object used as the lookup key. Strings are interpreted as the URL for a newRequest object.

• options

  • Can contain one possible property:ignoreMethod (Boolean). Whentrue, the request is considered to be aGET request regardless of its actual value.

Unlike the browser Cache API, Cloudflare Workers do not support theignoreSearch orignoreVary options onmatch(). You can accomplish this behavior by removing query strings or HTTP headers atput() time.

Our implementation of the Cache API respects the following HTTP headers on the request passed tomatch():

• Range

  • Results in a206 response if a matching response with a Content-Length header is found. Your Cloudflare cache always respects range requests, even if anAccept-Ranges header is on the response.

• If-Modified-Since

  • Results in a304 response if a matching response is found with aLast-Modified header with a value before the time specified inIf-Modified-Since.

• If-None-Match

  • Results in a304 response if a matching response is found with anETag header with a value that matches a value inIf-None-Match.

cache.match generates a504 error response when the requested content is missing or expired. The Cache API does not expose this504 directly to the Worker script, instead returningundefined. Nevertheless, the underlying504 is still visible in Cloudflare Logs.

If you use Cloudflare Logs, you may see these504 responses with theRequestSource ofedgeWorkerCacheAPI. Again, these are expected if the cached asset was missing or expired. Note thatedgeWorkerCacheAPI requests are already filtered out in other views, such as Cache Analytics. To filter out these requests or to filter requests by end users of your website only, refer toFilter end users.

cache.delete(request,options);

• delete(request, options) : Promise<boolean>

Deletes theResponse object from the cache and returns aPromise for a Boolean response:

• true: The response was cached but is now deleted
• false: The response was not in the cache at the time of deletion.

• request string | Request

  • The string orRequest object used as the lookup key. Strings are interpreted as the URL for a newRequest object.

• options object

  • Can contain one possible property:ignoreMethod (Boolean). Consider the request method a GET regardless of its actual value.

• How the cache works
• Example: Cache usingfetch()
• Example: using the Cache API
• Example: caching POST requests