1# Cache Reserve API
2 
3## Workers Integration
4 
5```
6┌────────────────────────────────────────────────────────────────┐
7│ CRITICAL: Workers Cache API ≠ Cache Reserve                   │
8│                                                                │
9│ • Workers caches.default / cache.put() → edge cache ONLY      │
10│ • Cache Reserve → zone-level setting, automatic, no per-req   │
11│ • You CANNOT selectively write to Cache Reserve from Workers  │
12│ • Cache Reserve works with standard fetch(), not cache.put()  │
13└────────────────────────────────────────────────────────────────┘
14```
15 
16Cache Reserve is a **zone-level configuration**, not a per-request API. It works automatically when enabled for the zone:
17 
18### Standard Fetch (Recommended)
19 
20```typescript
21// Cache Reserve works automatically via standard fetch
22export default {
23  async fetch(request: Request, env: Env): Promise<Response> {
24    // Standard fetch uses Cache Reserve automatically
25    return await fetch(request);
26  }
27};
28```
29 
30### Cache API Limitations
31 
32**IMPORTANT**: `cache.put()` is **NOT compatible** with Cache Reserve or Tiered Cache.
33 
34```typescript
35// ❌ WRONG: cache.put() bypasses Cache Reserve
36const cache = caches.default;
37let response = await cache.match(request);
38if (!response) {
39  response = await fetch(request);
40  await cache.put(request, response.clone()); // Bypasses Cache Reserve!
41}
42 
43// ✅ CORRECT: Use standard fetch for Cache Reserve compatibility
44return await fetch(request);
45 
46// ✅ CORRECT: Use Cache API only for custom cache namespaces
47const customCache = await caches.open('my-custom-cache');
48let response = await customCache.match(request);
49if (!response) {
50  response = await fetch(request);
51  await customCache.put(request, response.clone()); // Custom cache OK
52}
53```
54 
55## Purging and Cache Management
56 
57### Purge by URL (Instant)
58 
59```typescript
60// Purge specific URL from Cache Reserve immediately
61const purgeCacheReserveByURL = async (
62  zoneId: string,
63  apiToken: string,
64  urls: string[]
65) => {
66  const response = await fetch(
67    `https://api.cloudflare.com/client/v4/zones/${zoneId}/purge_cache`,
68    {
69      method: 'POST',
70      headers: {
71        'Authorization': `Bearer ${apiToken}`,
72        'Content-Type': 'application/json',
73      },
74      body: JSON.stringify({ files: urls })
75    }
76  );
77  return await response.json();
78};
79 
80// Example usage
81await purgeCacheReserveByURL('zone123', 'token456', [
82  'https://example.com/image.jpg',
83  'https://example.com/video.mp4'
84]);
85```
86 
87### Purge by Tag/Host/Prefix (Revalidation)
88 
89```typescript
90// Purge by cache tag - forces revalidation, not immediate removal
91await fetch(
92  `https://api.cloudflare.com/client/v4/zones/${zoneId}/purge_cache`,
93  {
94    method: 'POST',
95    headers: { 'Authorization': `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
96    body: JSON.stringify({ tags: ['tag1', 'tag2'] })
97  }
98);
99```
100 
101**Purge behavior:**
102- **By URL**: Immediate removal from Cache Reserve + edge cache
103- **By tag/host/prefix**: Revalidation only, assets remain in storage (costs continue)
104 
105### Clear All Cache Reserve Data
106 
107```typescript
108// Requires Cache Reserve OFF first
109await fetch(
110  `https://api.cloudflare.com/client/v4/zones/${zoneId}/cache/cache_reserve_clear`,
111  { method: 'POST', headers: { 'Authorization': `Bearer ${apiToken}` } }
112);
113 
114// Check status: GET same endpoint returns { state: "In-progress" | "Completed" }
115```
116 
117**Process**: Disable Cache Reserve → Call clear endpoint → Wait up to 24hr → Re-enable
118 
119## Monitoring and Analytics
120 
121### Dashboard Analytics
122 
123Navigate to **Caching > Cache Reserve** to view:
124 
125- **Egress Savings**: Total bytes served from Cache Reserve vs origin egress cost saved
126- **Requests Served**: Cache Reserve hits vs misses breakdown
127- **Storage Used**: Current GB stored in Cache Reserve (billed monthly)
128- **Operations**: Class A (writes) and Class B (reads) operation counts
129- **Cost Tracking**: Estimated monthly costs based on current usage
130 
131### Logpush Integration
132 
133```typescript
134// Logpush field: CacheReserveUsed (boolean) - filter for Cache Reserve hits
135// Query Cache Reserve hits in analytics
136const logpushQuery = `
137  SELECT 
138    ClientRequestHost, 
139    COUNT(*) as requests, 
140    SUM(EdgeResponseBytes) as bytes_served,
141    COUNT(CASE WHEN CacheReserveUsed = true THEN 1 END) as cache_reserve_hits,
142    COUNT(CASE WHEN CacheReserveUsed = false THEN 1 END) as cache_reserve_misses
143  FROM http_requests 
144  WHERE Timestamp >= NOW() - INTERVAL '24 hours'
145  GROUP BY ClientRequestHost 
146  ORDER BY requests DESC
147`;
148 
149// Filter only Cache Reserve hits
150const crHitsQuery = `
151  SELECT ClientRequestHost, COUNT(*) as requests, SUM(EdgeResponseBytes) as bytes
152  FROM http_requests 
153  WHERE CacheReserveUsed = true AND Timestamp >= NOW() - INTERVAL '7 days'
154  GROUP BY ClientRequestHost 
155  ORDER BY bytes DESC
156`;
157```
158 
159### GraphQL Analytics
160 
161```graphql
162query CacheReserveAnalytics($zoneTag: string, $since: string, $until: string) {
163  viewer {
164    zones(filter: { zoneTag: $zoneTag }) {
165      httpRequests1dGroups(
166        filter: { datetime_geq: $since, datetime_leq: $until }
167        limit: 1000
168      ) {
169        dimensions { date }
170        sum {
171          cachedBytes
172          cachedRequests
173          bytes
174          requests
175        }
176      }
177    }
178  }
179}
180```
181 
182## Pricing
183 
184```typescript
185// Storage: $0.015/GB-month | Class A (writes): $4.50/M | Class B (reads): $0.36/M
186// Cache miss: 1A + 1B | Cache hit: 1B | Assets >1GB: proportionally more ops
187```
188 
189## See Also
190 
191- [README](./README.md) - Overview and core concepts
192- [Configuration](./configuration.md) - Setup and Cache Rules
193- [Patterns](./patterns.md) - Best practices and optimization
194- [Gotchas](./gotchas.md) - Common issues and troubleshooting
195