0
# Context Caching
1

2
The Caches module provides context caching functionality to improve efficiency and reduce costs by caching large context data that is reused across multiple requests.
3

4
## Capabilities
5

6
### create
7

8
Create a new cached content instance.
9

10
```typescript { .api }
11
/**
12
 * Create cached content
13
 * @param params - Cache creation parameters
14
 * @returns Promise resolving to cached content
15
 */
16
function create(
17
  params: CreateCachedContentParameters
18
): Promise<CachedContent>;
19

20
interface CreateCachedContentParameters {
21
  /** Model name (e.g., 'gemini-2.0-flash-001') */
22
  model: string;
23
  /** Content to cache */
24
  contents: ContentListUnion;
25
  /** Cache configuration */
26
  config?: CachedContentConfig;
27
}
28

29
interface CachedContent {
30
  /** Cache name (unique identifier) */
31
  name?: string;
32
  /** Model name */
33
  model?: string;
34
  /** Creation timestamp */
35
  createTime?: string;
36
  /** Last update timestamp */
37
  updateTime?: string;
38
  /** Expiration timestamp */
39
  expireTime?: string;
40
  /** Time to live (e.g., '3600s') */
41
  ttl?: string;
42
  /** Cached contents */
43
  contents?: Content[];
44
  /** Tools in cache */
45
  tools?: Tool[];
46
  /** Tool configuration */
47
  toolConfig?: ToolConfig;
48
  /** System instruction in cache */
49
  systemInstruction?: Content;
50
}
51
```
52

53
**Usage Examples:**
54

55
```typescript
56
import { GoogleGenAI } from '@google/genai';
57

58
const client = new GoogleGenAI({ apiKey: 'YOUR_API_KEY' });
59

60
// Create cache with large document
61
const cache = await client.caches.create({
62
  model: 'gemini-2.0-flash-001',
63
  contents: [
64
    {
65
      role: 'user',
66
      parts: [{
67
        text: 'Here is a large document...' // Large context
68
      }]
69
    }
70
  ],
71
  config: {
72
    ttl: '3600s' // Cache for 1 hour
73
  }
74
});
75

76
console.log('Cache created:', cache.name);
77

78
// Use cache in generation
79
const response = await client.models.generateContent({
80
  model: 'gemini-2.0-flash',
81
  contents: 'Summarize the document',
82
  config: {
83
    cachedContent: cache.name
84
  }
85
});
86

87
console.log(response.text);
88
```
89

90
### list
91

92
List all cached contents with pagination.
93

94
```typescript { .api }
95
/**
96
 * List cached contents
97
 * @param params - List parameters
98
 * @returns Promise resolving to pager of cached contents
99
 */
100
function list(
101
  params?: ListCachedContentsParameters
102
): Promise<Pager<CachedContent>>;
103

104
interface ListCachedContentsParameters {
105
  /** Page size */
106
  pageSize?: number;
107
  /** Page token for pagination */
108
  pageToken?: string;
109
}
110
```
111

112
**Usage Examples:**
113

114
```typescript
115
// List all caches
116
const pager = await client.caches.list({
117
  pageSize: 10
118
});
119

120
for await (const cache of pager) {
121
  console.log(`Cache: ${cache.name}`);
122
  console.log(`  Model: ${cache.model}`);
123
  console.log(`  Expires: ${cache.expireTime}`);
124
}
125

126
// Manual pagination
127
const page1 = await client.caches.list({ pageSize: 5 });
128
console.log('First page:', page1.page);
129

130
if (page1.hasNextPage()) {
131
  const page2 = await page1.nextPage();
132
  console.log('Second page:', page2);
133
}
134
```
135

136
### get
137

138
Retrieve a specific cached content by name.
139

140
```typescript { .api }
141
/**
142
 * Get cached content by name
143
 * @param params - Get parameters
144
 * @returns Promise resolving to cached content
145
 */
146
function get(
147
  params: GetCachedContentParameters
148
): Promise<CachedContent>;
149

150
interface GetCachedContentParameters {
151
  /** Cache name */
152
  cachedContent: string;
153
}
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
// Get cache details
160
const cache = await client.caches.get({
161
  cachedContent: 'cachedContents/abc123'
162
});
163

164
console.log('Cache:', cache);
165
console.log('TTL:', cache.ttl);
166
console.log('Contents:', cache.contents);
167
```
168

169
### update
170

171
Update cached content metadata (mainly TTL).
172

173
```typescript { .api }
174
/**
175
 * Update cached content (TTL, etc.)
176
 * @param params - Update parameters
177
 * @returns Promise resolving to updated cached content
178
 */
179
function update(
180
  params: UpdateCachedContentParameters
181
): Promise<CachedContent>;
182

183
interface UpdateCachedContentParameters {
184
  /** Cache name */
185
  cachedContent: string;
186
  /** New time to live */
187
  ttl?: string;
188
}
189
```
190

191
**Usage Examples:**
192

193
```typescript
194
// Extend cache TTL
195
const updated = await client.caches.update({
196
  cachedContent: 'cachedContents/abc123',
197
  ttl: '7200s' // Extend to 2 hours
198
});
199

200
console.log('New expiration:', updated.expireTime);
201
```
202

203
### delete
204

205
Delete a cached content.
206

207
```typescript { .api }
208
/**
209
 * Delete cached content
210
 * @param params - Delete parameters
211
 * @returns Promise resolving to deletion response
212
 */
213
function delete(
214
  params: DeleteCachedContentParameters
215
): Promise<DeleteCachedContentResponse>;
216

217
interface DeleteCachedContentParameters {
218
  /** Cache name */
219
  cachedContent: string;
220
}
221

222
interface DeleteCachedContentResponse {
223
  /** Empty response on success */
224
}
225
```
226

227
**Usage Examples:**
228

229
```typescript
230
// Delete cache
231
await client.caches.delete({
232
  cachedContent: 'cachedContents/abc123'
233
});
234

235
console.log('Cache deleted');
236
```
237

238
## Types
239

240
### CachedContentConfig
241

242
Configuration for cache creation.
243

244
```typescript { .api }
245
interface CachedContentConfig {
246
  /** Time to live (e.g., '3600s', '1h') */
247
  ttl?: string;
248
  /** Expiration time (absolute timestamp) */
249
  expireTime?: string;
250
  /** Display name for cache */
251
  displayName?: string;
252
  /** System instruction */
253
  systemInstruction?: Content | string;
254
  /** Tools to cache */
255
  tools?: ToolListUnion;
256
  /** Tool configuration */
257
  toolConfig?: ToolConfig;
258
}
259
```
260

261
### Content
262

263
Cached content structure.
264

265
```typescript { .api }
266
interface Content {
267
  /** List of content parts */
268
  parts?: Part[];
269
  /** Role ('user' or 'model') */
270
  role?: string;
271
}
272

273
interface Part {
274
  /** Text content */
275
  text?: string;
276
  /** Inline binary data */
277
  inlineData?: Blob;
278
  /** File reference */
279
  fileData?: FileData;
280
}
281
```
282

283
## Complete Examples
284

285
### Cache Large Document
286

287
```typescript
288
import { GoogleGenAI } from '@google/genai';
289
import * as fs from 'fs';
290

291
const client = new GoogleGenAI({ apiKey: 'YOUR_API_KEY' });
292

293
// Read large document
294
const largeDocument = fs.readFileSync('./large_document.txt', 'utf-8');
295

296
// Create cache
297
const cache = await client.caches.create({
298
  model: 'gemini-2.0-flash-001',
299
  contents: [{
300
    role: 'user',
301
    parts: [{ text: largeDocument }]
302
  }],
303
  config: {
304
    displayName: 'Large Document Cache',
305
    ttl: '7200s' // 2 hours
306
  }
307
});
308

309
console.log('Cache created:', cache.name);
310

311
// Use cache for multiple queries
312
const queries = [
313
  'Summarize the main points',
314
  'What are the key findings?',
315
  'Extract action items'
316
];
317

318
for (const query of queries) {
319
  const response = await client.models.generateContent({
320
    model: 'gemini-2.0-flash',
321
    contents: query,
322
    config: {
323
      cachedContent: cache.name
324
    }
325
  });
326

327
  console.log(`\nQuery: ${query}`);
328
  console.log(`Response: ${response.text}`);
329

330
  // Check token savings
331
  if (response.usageMetadata?.cachedContentTokenCount) {
332
    console.log(`Cached tokens: ${response.usageMetadata.cachedContentTokenCount}`);
333
  }
334
}
335
```
336

337
### Cache with System Instructions and Tools
338

339
```typescript
340
import { Type } from '@google/genai';
341

342
// Create cache with system instruction and tools
343
const cache = await client.caches.create({
344
  model: 'gemini-2.0-flash-001',
345
  contents: [{
346
    role: 'user',
347
    parts: [{ text: 'Product catalog data...' }]
348
  }],
349
  config: {
350
    displayName: 'Product Catalog Cache',
351
    ttl: '3600s',
352
    systemInstruction: 'You are a product recommendation assistant.',
353
    tools: [{
354
      functionDeclarations: [{
355
        name: 'searchProducts',
356
        description: 'Search product catalog',
357
        parameters: {
358
          type: Type.OBJECT,
359
          properties: {
360
            query: { type: Type.STRING }
361
          }
362
        }
363
      }]
364
    }]
365
  }
366
});
367

368
// Use cache with tools
369
const response = await client.models.generateContent({
370
  model: 'gemini-2.0-flash',
371
  contents: 'Find laptops under $1000',
372
  config: {
373
    cachedContent: cache.name
374
  }
375
});
376
```
377

378
### Manage Cache Lifecycle
379

380
```typescript
381
// Create cache
382
const cache = await client.caches.create({
383
  model: 'gemini-2.0-flash-001',
384
  contents: [{ role: 'user', parts: [{ text: 'Context data' }] }],
385
  config: {
386
    ttl: '1800s' // 30 minutes
387
  }
388
});
389

390
console.log('Cache created:', cache.name);
391
console.log('Expires at:', cache.expireTime);
392

393
// Use cache
394
const response1 = await client.models.generateContent({
395
  model: 'gemini-2.0-flash',
396
  contents: 'Question 1',
397
  config: { cachedContent: cache.name }
398
});
399

400
// Check if still valid
401
const currentCache = await client.caches.get({
402
  cachedContent: cache.name!
403
});
404

405
console.log('Cache still valid:', new Date(currentCache.expireTime!) > new Date());
406

407
// Extend TTL if needed
408
if (new Date(currentCache.expireTime!) < new Date(Date.now() + 600000)) {
409
  const extended = await client.caches.update({
410
    cachedContent: cache.name!,
411
    ttl: '3600s'
412
  });
413
  console.log('Cache extended to:', extended.expireTime);
414
}
415

416
// Use more
417
const response2 = await client.models.generateContent({
418
  model: 'gemini-2.0-flash',
419
  contents: 'Question 2',
420
  config: { cachedContent: cache.name }
421
});
422

423
// Clean up when done
424
await client.caches.delete({
425
  cachedContent: cache.name!
426
});
427

428
console.log('Cache deleted');
429
```
430

431
### Cache Multiple Files
432

433
```typescript
434
// Upload files first
435
const file1 = await client.files.upload({
436
  file: './document1.pdf',
437
  mimeType: 'application/pdf'
438
});
439

440
const file2 = await client.files.upload({
441
  file: './document2.pdf',
442
  mimeType: 'application/pdf'
443
});
444

445
// Create cache with multiple files
446
const cache = await client.caches.create({
447
  model: 'gemini-2.0-flash-001',
448
  contents: [{
449
    role: 'user',
450
    parts: [
451
      { text: 'Analyze these documents:' },
452
      {
453
        fileData: {
454
          fileUri: file1.uri!,
455
          mimeType: 'application/pdf'
456
        }
457
      },
458
      {
459
        fileData: {
460
          fileUri: file2.uri!,
461
          mimeType: 'application/pdf'
462
        }
463
      }
464
    ]
465
  }],
466
  config: {
467
    displayName: 'Multi-Document Cache',
468
    ttl: '7200s'
469
  }
470
});
471

472
// Query across cached documents
473
const response = await client.models.generateContent({
474
  model: 'gemini-2.0-flash',
475
  contents: 'Compare the two documents',
476
  config: {
477
    cachedContent: cache.name
478
  }
479
});
480
```
481

482
### List and Clean Up Old Caches
483

484
```typescript
485
// List all caches
486
const caches = await client.caches.list();
487

488
const now = new Date();
489

490
for await (const cache of caches) {
491
  const expireTime = new Date(cache.expireTime!);
492

493
  console.log(`Cache: ${cache.name}`);
494
  console.log(`  Expires: ${cache.expireTime}`);
495

496
  // Delete expired or soon-to-expire caches
497
  if (expireTime < new Date(now.getTime() + 300000)) { // 5 minutes
498
    console.log('  Deleting...');
499
    await client.caches.delete({
500
      cachedContent: cache.name!
501
    });
502
  }
503
}
504
```
505

506
### Token Usage with Caching
507

508
```typescript
509
const largeContext = 'Large document content...'; // 10000+ tokens
510

511
// Create cache
512
const cache = await client.caches.create({
513
  model: 'gemini-2.0-flash-001',
514
  contents: [{ role: 'user', parts: [{ text: largeContext }] }],
515
  config: { ttl: '3600s' }
516
});
517

518
// First request without cache
519
const response1 = await client.models.generateContent({
520
  model: 'gemini-2.0-flash',
521
  contents: [
522
    { role: 'user', parts: [{ text: largeContext }] },
523
    { role: 'user', parts: [{ text: 'Question?' }] }
524
  ]
525
});
526

527
console.log('Without cache:');
528
console.log('  Prompt tokens:', response1.usageMetadata?.promptTokenCount);
529

530
// Second request with cache
531
const response2 = await client.models.generateContent({
532
  model: 'gemini-2.0-flash',
533
  contents: 'Question?',
534
  config: { cachedContent: cache.name }
535
});
536

537
console.log('With cache:');
538
console.log('  Prompt tokens:', response2.usageMetadata?.promptTokenCount);
539
console.log('  Cached tokens:', response2.usageMetadata?.cachedContentTokenCount);
540

541
// Token savings
542
const savings = (response1.usageMetadata?.promptTokenCount || 0) -
543
                (response2.usageMetadata?.promptTokenCount || 0);
544
console.log('Token savings:', savings);
545
```
546

547
### Cache for Chat Sessions
548

549
```typescript
550
// Create cache with conversation context
551
const cache = await client.caches.create({
552
  model: 'gemini-2.0-flash-001',
553
  contents: [
554
    { role: 'user', parts: [{ text: 'Background context...' }] },
555
    { role: 'model', parts: [{ text: 'I understand the context.' }] }
556
  ],
557
  config: {
558
    displayName: 'Conversation Context',
559
    ttl: '1800s',
560
    systemInstruction: 'You are a helpful assistant with this context.'
561
  }
562
});
563

564
// Create chat using cached context
565
const chat = client.chats.create({
566
  model: 'gemini-2.0-flash',
567
  config: {
568
    cachedContent: cache.name
569
  }
570
});
571

572
// Chat benefits from cached context
573
const r1 = await chat.sendMessage({ message: 'Question 1?' });
574
const r2 = await chat.sendMessage({ message: 'Question 2?' });
575

576
console.log('Chat responses use cached context');
577
```
578

579
### Error Handling
580

581
```typescript
582
try {
583
  // Create cache
584
  const cache = await client.caches.create({
585
    model: 'gemini-2.0-flash-001',
586
    contents: [{ role: 'user', parts: [{ text: 'Context' }] }],
587
    config: { ttl: '3600s' }
588
  });
589

590
  // Use cache
591
  const response = await client.models.generateContent({
592
    model: 'gemini-2.0-flash',
593
    contents: 'Query',
594
    config: { cachedContent: cache.name }
595
  });
596

597
  console.log(response.text);
598
} catch (error) {
599
  if (error.status === 404) {
600
    console.error('Cache not found or expired');
601
  } else if (error.status === 400) {
602
    console.error('Invalid cache configuration');
603
  } else {
604
    console.error('Cache error:', error);
605
  }
606
}
607
```
608

609
### Batch Operations with Shared Cache
610

611
```typescript
612
// Create shared cache for batch processing
613
const cache = await client.caches.create({
614
  model: 'gemini-2.0-flash-001',
615
  contents: [{
616
    role: 'user',
617
    parts: [{ text: 'Reference documentation...' }]
618
  }],
619
  config: {
620
    displayName: 'Batch Processing Cache',
621
    ttl: '7200s'
622
  }
623
});
624

625
// Process multiple items using shared cache
626
const items = ['Item 1', 'Item 2', 'Item 3', 'Item 4'];
627

628
const results = await Promise.all(
629
  items.map(item =>
630
    client.models.generateContent({
631
      model: 'gemini-2.0-flash',
632
      contents: `Process: ${item}`,
633
      config: { cachedContent: cache.name }
634
    })
635
  )
636
);
637

638
results.forEach((result, index) => {
639
  console.log(`Result ${index + 1}:`, result.text);
640
  console.log(`  Cached tokens: ${result.usageMetadata?.cachedContentTokenCount}`);
641
});
642

643
// Clean up
644
await client.caches.delete({ cachedContent: cache.name! });
645
```
646

647
### Using expireTime Instead of TTL
648

649
```typescript
650
// Set absolute expiration time
651
const expirationDate = new Date();
652
expirationDate.setHours(expirationDate.getHours() + 2);
653

654
const cache = await client.caches.create({
655
  model: 'gemini-2.0-flash-001',
656
  contents: [{ role: 'user', parts: [{ text: 'Context' }] }],
657
  config: {
658
    expireTime: expirationDate.toISOString()
659
  }
660
});
661

662
console.log('Cache expires at:', cache.expireTime);
663
```
664