Cache

Accelerate your agents with intelligent edge caching. Automatically cache content based on response headers and file extensions across 330+ global locations. For manual control, use the Workers Cache API to cache third-party API responses and custom content.

How Caching Works

The platform respects origin server cache headers in the following order:

Do NOT Cache

  • Cache-Control: private, no-store, no-cache, max-age=0
  • Set-Cookie header exists
  • HTTP method is not GET

Cache Please

  • Cache-Control: public with max-age > 0
  • Expires header set to future date
  • Default file extensions (CSS, JS, images, etc.)

Default Cached File Extensions

The following file types are automatically cached

  • Static Assets: CSS, JS, WOFF, WOFF2, TTF, ICO, SVG
  • Images: PNG, JPG, JPEG, GIF, WEBP, AVIF, BMP, TIFF, TIF
  • Media: MP4, MP3, OGG, FLAC, MKV, AVI, WEBM
  • Documents: PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX, EPS
  • Archives: ZIP, RAR, TAR, GZ, 7Z, BZ2, ZST
  • Other: APK, BIN, CLASS, DMG, EJS, EOT, EXE, ISO, JAR, MID, MIDI, OTF, PICT, PLS, PS, SWF

Note: HTML and JSON are NOT cached by default.

TypeScript API Reference

You can access the cache API via the global caches object available in Agents and MCP Tools:

typescript

Cache Management

caches.default
Access to the default cache namespace. This is the primary cache storage that persists across Worker executions and is shared globally.

caches.open(cacheName: string): Promise<Cache>
Opens a named cache namespace. Each namespace is isolated and allows you to organize cached content by purpose or application area.

Cache Operations

cache.match(request: Request | string): Promise<Response | undefined>
Retrieves a cached response for the given request. Returns undefined if no cached response exists. The request can be a full Request object or a string URL.

cache.put(request: Request | string, response: Response): Promise<void>
Stores a response in the cache for the given request key. The response must be a valid Response object. Note that the response body can only be consumed once, so use response.clone() if you need to use the response elsewhere.

cache.delete(request: Request | string): Promise<boolean>
Removes a cached response for the given request key. Returns true if a cached response was found and deleted, false if no cached response existed.

cache.keys(request?: Request | string): Promise<ReadonlyArray<Request>>
Returns an array of Request objects representing all cached requests. If a request parameter is provided, only matching requests are returned.

Workers Cache API

Use the Cache API for manual control when automatic caching isn't sufficient:

Third-Party API Caching

typescript

Agent Response Caching

typescript

Cache Control Headers

CDN-Specific Headers

typescript

Cache Purging

Purge Specific URLs

typescript

Tiered Caching Strategy

Layered Cache Approach

typescript

Best Practices

✅ Recommended Patterns

typescript

❌ Anti-Patterns

typescript

Cache Limits

  • Object Size: 512MB maximum per cached response
  • Request Size: 128MB maximum for cache keys
  • Cache Storage: Shared across all Workers in your account
  • TTL Range: 1 second minimum, no maximum

Related Services

Official Documentation