0
# Batch Processing
1

2
The Batches module provides batch processing capabilities for processing multiple requests efficiently using GCS or BigQuery integration, supporting both content generation and embeddings.
3

4
## Capabilities
5

6
### create
7

8
Create a batch generation job.
9

10
```typescript { .api }
11
/**
12
 * Create batch generation job
13
 * @param params - Batch job creation parameters
14
 * @returns Promise resolving to batch job
15
 */
16
function create(
17
  params: CreateBatchJobParameters
18
): Promise<BatchJob>;
19

20
interface CreateBatchJobParameters {
21
  /** Model name */
22
  model: string;
23
  /** Source (GCS URI, BigQuery URI, or inline requests) */
24
  src: BatchJobSourceUnion;
25
  /** Batch configuration */
26
  config?: BatchJobConfig;
27
}
28

29
interface BatchJob {
30
  /** Job name (unique identifier) */
31
  name?: string;
32
  /** Display name */
33
  displayName?: string;
34
  /** Model name */
35
  model?: string;
36
  /** Job state */
37
  state?: JobState;
38
  /** Creation timestamp */
39
  createTime?: string;
40
  /** Start timestamp */
41
  startTime?: string;
42
  /** End timestamp */
43
  endTime?: string;
44
  /** Source configuration */
45
  src?: BatchJobSource;
46
  /** Job configuration */
47
  config?: BatchJobConfig;
48
}
49
```
50

51
**Usage Examples:**
52

53
```typescript
54
import { GoogleGenAI } from '@google/genai';
55

56
const client = new GoogleGenAI({ apiKey: 'YOUR_API_KEY' });
57

58
// Create batch job with GCS source
59
const batchJob = await client.batches.create({
60
  model: 'gemini-2.0-flash',
61
  src: 'gs://my-bucket/batch-requests.jsonl',
62
  config: {
63
    destination: 'gs://my-bucket/batch-results/'
64
  }
65
});
66

67
console.log('Batch job created:', batchJob.name);
68
console.log('State:', batchJob.state);
69

70
// With inline requests
71
const inlineBatch = await client.batches.create({
72
  model: 'gemini-2.0-flash',
73
  src: [
74
    {
75
      contents: [{ role: 'user', parts: [{ text: 'Question 1' }] }]
76
    },
77
    {
78
      contents: [{ role: 'user', parts: [{ text: 'Question 2' }] }]
79
    },
80
    {
81
      contents: [{ role: 'user', parts: [{ text: 'Question 3' }] }]
82
    }
83
  ],
84
  config: {
85
    destination: 'gs://my-bucket/results/'
86
  }
87
});
88
```
89

90
### createEmbeddings
91

92
Create embeddings batch job (experimental, Gemini API only).
93

94
```typescript { .api }
95
/**
96
 * Create embeddings batch job
97
 * @param params - Embeddings batch job creation parameters
98
 * @returns Promise resolving to batch job
99
 */
100
function createEmbeddings(
101
  params: CreateEmbeddingsBatchJobParameters
102
): Promise<BatchJob>;
103

104
interface CreateEmbeddingsBatchJobParameters {
105
  /** Model name (e.g., 'text-embedding-004') */
106
  model: string;
107
  /** Source data */
108
  src: BatchJobSourceUnion;
109
  /** Batch configuration */
110
  config?: BatchJobConfig;
111
}
112
```
113

114
**Usage Examples:**
115

116
```typescript
117
// Create embeddings batch job
118
const embeddingsBatch = await client.batches.createEmbeddings({
119
  model: 'text-embedding-004',
120
  src: 'gs://my-bucket/texts.jsonl',
121
  config: {
122
    destination: 'gs://my-bucket/embeddings/'
123
  }
124
});
125

126
console.log('Embeddings batch job:', embeddingsBatch.name);
127
```
128

129
### list
130

131
List batch jobs with pagination.
132

133
```typescript { .api }
134
/**
135
 * List batch jobs with pagination
136
 * @param params - List parameters
137
 * @returns Promise resolving to pager of batch jobs
138
 */
139
function list(
140
  params?: ListBatchJobsParameters
141
): Promise<Pager<BatchJob>>;
142

143
interface ListBatchJobsParameters {
144
  /** Page size */
145
  pageSize?: number;
146
  /** Page token for pagination */
147
  pageToken?: string;
148
}
149
```
150

151
**Usage Examples:**
152

153
```typescript
154
// List all batch jobs
155
const pager = await client.batches.list({
156
  pageSize: 10
157
});
158

159
for await (const job of pager) {
160
  console.log(`Job: ${job.name}`);
161
  console.log(`  State: ${job.state}`);
162
  console.log(`  Model: ${job.model}`);
163
  console.log(`  Created: ${job.createTime}`);
164
}
165

166
// Manual pagination
167
const page1 = await client.batches.list({ pageSize: 5 });
168
console.log('First page:', page1.page);
169

170
if (page1.hasNextPage()) {
171
  const page2 = await page1.nextPage();
172
  console.log('Second page:', page2);
173
}
174
```
175

176
### get
177

178
Get batch job status and details.
179

180
```typescript { .api }
181
/**
182
 * Get batch job status
183
 * @param params - Get parameters
184
 * @returns Promise resolving to batch job
185
 */
186
function get(
187
  params: GetBatchJobParameters
188
): Promise<BatchJob>;
189

190
interface GetBatchJobParameters {
191
  /** Batch job name */
192
  batchJob: string;
193
}
194
```
195

196
**Usage Examples:**
197

198
```typescript
199
// Get job status
200
const job = await client.batches.get({
201
  batchJob: 'projects/123/locations/us-central1/batchJobs/abc'
202
});
203

204
console.log('Job state:', job.state);
205
console.log('Progress:', job);
206

207
// Poll until complete
208
while (job.state === JobState.JOB_STATE_RUNNING) {
209
  await new Promise(resolve => setTimeout(resolve, 10000));
210

211
  const updated = await client.batches.get({
212
    batchJob: job.name!
213
  });
214

215
  if (updated.state === JobState.JOB_STATE_SUCCEEDED) {
216
    console.log('Job completed successfully');
217
    break;
218
  } else if (updated.state === JobState.JOB_STATE_FAILED) {
219
    console.error('Job failed');
220
    break;
221
  }
222
}
223
```
224

225
### cancel
226

227
Cancel a running batch job.
228

229
```typescript { .api }
230
/**
231
 * Cancel running batch job
232
 * @param params - Cancel parameters
233
 * @returns Promise resolving when cancellation is initiated
234
 */
235
function cancel(
236
  params: CancelBatchJobParameters
237
): Promise<void>;
238

239
interface CancelBatchJobParameters {
240
  /** Batch job name */
241
  batchJob: string;
242
}
243
```
244

245
**Usage Examples:**
246

247
```typescript
248
// Cancel job
249
await client.batches.cancel({
250
  batchJob: 'projects/123/locations/us-central1/batchJobs/abc'
251
});
252

253
console.log('Cancellation requested');
254

255
// Verify cancellation
256
const cancelled = await client.batches.get({
257
  batchJob: 'projects/123/locations/us-central1/batchJobs/abc'
258
});
259

260
console.log('Job state:', cancelled.state);
261
```
262

263
### delete
264

265
Delete a batch job.
266

267
```typescript { .api }
268
/**
269
 * Delete batch job
270
 * @param params - Delete parameters
271
 * @returns Promise resolving to delete response
272
 */
273
function delete(
274
  params: DeleteBatchJobParameters
275
): Promise<DeleteResourceJob>;
276

277
interface DeleteBatchJobParameters {
278
  /** Batch job name */
279
  batchJob: string;
280
}
281

282
interface DeleteResourceJob {
283
  /** Empty response on success */
284
}
285
```
286

287
**Usage Examples:**
288

289
```typescript
290
// Delete completed job
291
await client.batches.delete({
292
  batchJob: 'projects/123/locations/us-central1/batchJobs/abc'
293
});
294

295
console.log('Batch job deleted');
296
```
297

298
## Types
299

300
### BatchJobConfig
301

302
Configuration for batch jobs.
303

304
```typescript { .api }
305
interface BatchJobConfig {
306
  /** Destination (GCS URI or BigQuery URI) */
307
  destination?: BatchJobDestinationUnion;
308
  /** Display name */
309
  displayName?: string;
310
  /** Generation configuration */
311
  generationConfig?: GenerateContentConfig;
312
}
313
```
314

315
### BatchJobSource
316

317
Source configuration for batch jobs.
318

319
```typescript { .api }
320
interface BatchJobSource {
321
  /** GCS URI (e.g., 'gs://bucket/file.jsonl') */
322
  gcsUri?: string;
323
  /** BigQuery URI (e.g., 'bq://project.dataset.table') */
324
  bigqueryUri?: string;
325
}
326

327
/** GCS URI, BigQuery URI, or inline requests array */
328
type BatchJobSourceUnion = BatchJobSource | InlinedRequest[] | string;
329
```
330

331
### BatchJobDestination
332

333
Destination configuration for batch results.
334

335
```typescript { .api }
336
interface BatchJobDestination {
337
  /** GCS URI (e.g., 'gs://bucket/results/') */
338
  gcsUri?: string;
339
  /** BigQuery URI (e.g., 'bq://project.dataset.table') */
340
  bigqueryUri?: string;
341
}
342

343
/** GCS URI, BigQuery URI string, or destination object */
344
type BatchJobDestinationUnion = BatchJobDestination | string;
345
```
346

347
### InlinedRequest
348

349
Single request in inline batch.
350

351
```typescript { .api }
352
interface InlinedRequest {
353
  /** Request contents */
354
  contents: ContentListUnion;
355
  /** Request-specific config */
356
  config?: GenerateContentConfig;
357
}
358
```
359

360
### JobState
361

362
Batch job states.
363

364
```typescript { .api }
365
enum JobState {
366
  JOB_STATE_UNSPECIFIED = 'JOB_STATE_UNSPECIFIED',
367
  JOB_STATE_QUEUED = 'JOB_STATE_QUEUED',
368
  JOB_STATE_PENDING = 'JOB_STATE_PENDING',
369
  JOB_STATE_RUNNING = 'JOB_STATE_RUNNING',
370
  JOB_STATE_SUCCEEDED = 'JOB_STATE_SUCCEEDED',
371
  JOB_STATE_FAILED = 'JOB_STATE_FAILED',
372
  JOB_STATE_CANCELLING = 'JOB_STATE_CANCELLING',
373
  JOB_STATE_CANCELLED = 'JOB_STATE_CANCELLED',
374
  JOB_STATE_PAUSED = 'JOB_STATE_PAUSED',
375
  JOB_STATE_EXPIRED = 'JOB_STATE_EXPIRED',
376
  JOB_STATE_UPDATING = 'JOB_STATE_UPDATING',
377
  JOB_STATE_PARTIALLY_SUCCEEDED = 'JOB_STATE_PARTIALLY_SUCCEEDED'
378
}
379
```
380

381
## Complete Examples
382

383
### Batch Generation with GCS
384

385
```typescript
386
import { GoogleGenAI } from '@google/genai';
387
import * as fs from 'fs';
388

389
const client = new GoogleGenAI({ apiKey: 'YOUR_API_KEY' });
390

391
// Prepare JSONL file with requests
392
const requests = [
393
  { contents: [{ role: 'user', parts: [{ text: 'Translate to French: Hello' }] }] },
394
  { contents: [{ role: 'user', parts: [{ text: 'Translate to French: Goodbye' }] }] },
395
  { contents: [{ role: 'user', parts: [{ text: 'Translate to French: Thank you' }] }] }
396
];
397

398
const jsonl = requests.map(r => JSON.stringify(r)).join('\n');
399
fs.writeFileSync('./batch-requests.jsonl', jsonl);
400

401
// Upload to GCS (using Google Cloud Storage client)
402
// await uploadToGCS('./batch-requests.jsonl', 'gs://my-bucket/batch-requests.jsonl');
403

404
// Create batch job
405
const job = await client.batches.create({
406
  model: 'gemini-2.0-flash',
407
  src: 'gs://my-bucket/batch-requests.jsonl',
408
  config: {
409
    destination: 'gs://my-bucket/batch-results/',
410
    displayName: 'Translation Batch'
411
  }
412
});
413

414
console.log('Batch job created:', job.name);
415

416
// Poll for completion
417
const pollBatchJob = async (jobName: string) => {
418
  let currentJob = await client.batches.get({ batchJob: jobName });
419

420
  while (
421
    currentJob.state === JobState.JOB_STATE_RUNNING ||
422
    currentJob.state === JobState.JOB_STATE_PENDING ||
423
    currentJob.state === JobState.JOB_STATE_QUEUED
424
  ) {
425
    console.log('Job state:', currentJob.state);
426
    await new Promise(resolve => setTimeout(resolve, 30000)); // Wait 30s
427

428
    currentJob = await client.batches.get({ batchJob: jobName });
429
  }
430

431
  return currentJob;
432
};
433

434
const completed = await pollBatchJob(job.name!);
435

436
if (completed.state === JobState.JOB_STATE_SUCCEEDED) {
437
  console.log('Batch job completed successfully');
438
  console.log('Results at:', completed.config?.destination);
439
} else {
440
  console.error('Batch job failed:', completed.state);
441
}
442
```
443

444
### Inline Batch Processing
445

446
```typescript
447
// Create batch with inline requests
448
const requests = [];
449
for (let i = 1; i <= 100; i++) {
450
  requests.push({
451
    contents: [{ role: 'user', parts: [{ text: `Summarize topic ${i}` }] }]
452
  });
453
}
454

455
const batchJob = await client.batches.create({
456
  model: 'gemini-2.0-flash',
457
  src: requests,
458
  config: {
459
    destination: 'gs://my-bucket/summaries/',
460
    displayName: 'Topic Summaries Batch',
461
    generationConfig: {
462
      temperature: 0.7,
463
      maxOutputTokens: 512
464
    }
465
  }
466
});
467

468
console.log('Processing', requests.length, 'requests');
469
```
470

471
### BigQuery Integration
472

473
```typescript
474
// Batch job with BigQuery source and destination
475
const batchJob = await client.batches.create({
476
  model: 'gemini-2.0-flash',
477
  src: 'bq://my-project.my-dataset.input_table',
478
  config: {
479
    destination: 'bq://my-project.my-dataset.output_table',
480
    displayName: 'BigQuery Batch Processing'
481
  }
482
});
483

484
console.log('BigQuery batch job:', batchJob.name);
485

486
// Poll and wait
487
const completed = await pollBatchJob(batchJob.name!);
488

489
if (completed.state === JobState.JOB_STATE_SUCCEEDED) {
490
  console.log('Results written to BigQuery table');
491
}
492
```
493

494
### Embeddings Batch Job
495

496
```typescript
497
// Prepare texts for embedding
498
const texts = [
499
  'Text document 1',
500
  'Text document 2',
501
  'Text document 3',
502
  // ... many more
503
];
504

505
// Write to JSONL
506
const jsonl = texts.map(text =>
507
  JSON.stringify({ contents: [{ role: 'user', parts: [{ text }] }] })
508
).join('\n');
509

510
// Upload to GCS
511
// await uploadToGCS(jsonl, 'gs://my-bucket/texts.jsonl');
512

513
// Create embeddings batch
514
const embeddingJob = await client.batches.createEmbeddings({
515
  model: 'text-embedding-004',
516
  src: 'gs://my-bucket/texts.jsonl',
517
  config: {
518
    destination: 'gs://my-bucket/embeddings/',
519
    displayName: 'Text Embeddings Batch'
520
  }
521
});
522

523
console.log('Embeddings job:', embeddingJob.name);
524

525
// Wait for completion
526
const completed = await pollBatchJob(embeddingJob.name!);
527
console.log('Embeddings ready at:', completed.config?.destination);
528
```
529

530
### Batch Job Management
531

532
```typescript
533
// List all running jobs
534
const jobs = await client.batches.list();
535

536
for await (const job of jobs) {
537
  console.log(`\nJob: ${job.name}`);
538
  console.log(`  Display Name: ${job.displayName}`);
539
  console.log(`  State: ${job.state}`);
540
  console.log(`  Model: ${job.model}`);
541
  console.log(`  Created: ${job.createTime}`);
542

543
  // Cancel long-running jobs
544
  if (job.state === JobState.JOB_STATE_RUNNING) {
545
    const created = new Date(job.createTime!);
546
    const now = new Date();
547
    const hoursRunning = (now.getTime() - created.getTime()) / (1000 * 60 * 60);
548

549
    if (hoursRunning > 2) {
550
      console.log('  Cancelling long-running job...');
551
      await client.batches.cancel({ batchJob: job.name! });
552
    }
553
  }
554

555
  // Delete completed jobs
556
  if (
557
    job.state === JobState.JOB_STATE_SUCCEEDED ||
558
    job.state === JobState.JOB_STATE_FAILED ||
559
    job.state === JobState.JOB_STATE_CANCELLED
560
  ) {
561
    const ended = new Date(job.endTime!);
562
    const now = new Date();
563
    const daysOld = (now.getTime() - ended.getTime()) / (1000 * 60 * 60 * 24);
564

565
    if (daysOld > 7) {
566
      console.log('  Deleting old job...');
567
      await client.batches.delete({ batchJob: job.name! });
568
    }
569
  }
570
}
571
```
572

573
### Error Handling and Retry
574

575
```typescript
576
async function createBatchWithRetry(
577
  params: CreateBatchJobParameters,
578
  maxRetries: number = 3
579
): Promise<BatchJob> {
580
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
581
    try {
582
      const job = await client.batches.create(params);
583
      console.log(`Batch job created on attempt ${attempt}`);
584
      return job;
585
    } catch (error) {
586
      console.error(`Attempt ${attempt} failed:`, error);
587

588
      if (attempt === maxRetries) {
589
        throw error;
590
      }
591

592
      const backoffMs = Math.pow(2, attempt) * 1000;
593
      await new Promise(resolve => setTimeout(resolve, backoffMs));
594
    }
595
  }
596

597
  throw new Error('Max retries exceeded');
598
}
599

600
// Use with retry logic
601
const job = await createBatchWithRetry({
602
  model: 'gemini-2.0-flash',
603
  src: 'gs://my-bucket/requests.jsonl',
604
  config: {
605
    destination: 'gs://my-bucket/results/'
606
  }
607
});
608
```
609

610
### Parallel Batch Jobs
611

612
```typescript
613
// Create multiple batch jobs in parallel
614
const batches = [
615
  {
616
    model: 'gemini-2.0-flash',
617
    src: 'gs://my-bucket/batch1.jsonl',
618
    config: { destination: 'gs://my-bucket/results1/' }
619
  },
620
  {
621
    model: 'gemini-2.0-flash',
622
    src: 'gs://my-bucket/batch2.jsonl',
623
    config: { destination: 'gs://my-bucket/results2/' }
624
  },
625
  {
626
    model: 'gemini-2.0-flash',
627
    src: 'gs://my-bucket/batch3.jsonl',
628
    config: { destination: 'gs://my-bucket/results3/' }
629
  }
630
];
631

632
const jobs = await Promise.all(
633
  batches.map(params => client.batches.create(params))
634
);
635

636
console.log(`Created ${jobs.length} batch jobs`);
637

638
// Wait for all to complete
639
const results = await Promise.all(
640
  jobs.map(job => pollBatchJob(job.name!))
641
);
642

643
// Check results
644
results.forEach((result, index) => {
645
  console.log(`Batch ${index + 1}:`, result.state);
646
});
647
```
648

649
### Download and Process Results
650

651
```typescript
652
import { Storage } from '@google-cloud/storage';
653

654
const storage = new Storage();
655

656
// Wait for batch to complete
657
const completed = await pollBatchJob(batchJob.name!);
658

659
if (completed.state === JobState.JOB_STATE_SUCCEEDED) {
660
  // Parse GCS destination
661
  const destUri = completed.config?.destination as string;
662
  const [, bucket, ...pathParts] = destUri.replace('gs://', '').split('/');
663
  const prefix = pathParts.join('/');
664

665
  // List result files
666
  const [files] = await storage.bucket(bucket).getFiles({ prefix });
667

668
  // Download and process each result file
669
  for (const file of files) {
670
    const [content] = await file.download();
671
    const lines = content.toString().split('\n').filter(l => l.trim());
672

673
    lines.forEach(line => {
674
      const result = JSON.parse(line);
675
      console.log('Result:', result);
676
    });
677
  }
678
}
679
```
680

681
### Batch with Configuration
682

683
```typescript
684
import { HarmCategory, HarmBlockThreshold } from '@google/genai';
685

686
const batchJob = await client.batches.create({
687
  model: 'gemini-2.0-flash',
688
  src: 'gs://my-bucket/requests.jsonl',
689
  config: {
690
    destination: 'gs://my-bucket/results/',
691
    displayName: 'Configured Batch Job',
692
    generationConfig: {
693
      temperature: 0.9,
694
      topP: 0.95,
695
      topK: 40,
696
      maxOutputTokens: 2048,
697
      safetySettings: [
698
        {
699
          category: HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
700
          threshold: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE
701
        }
702
      ],
703
      systemInstruction: 'You are a helpful assistant.'
704
    }
705
  }
706
});
707
```
708