Update a context cache

You can update when a context cache expires. The default expiration time of acontext cache is 60 minutes after its creation time. An expired context cache isdeleted during a garbage collection process and can't be used or updated. Toupdate the time when an unexpired context cache expires, update one of itsfollowing properties:

  • ttl - The number of seconds and nanoseconds that the cache lives after it'screated or after thettl is updated before it expires. When you set thettl, theexpireTime of the cache is updated.

  • expire_time - ATimestamp that specifies the absolute date and time whenthe context cache expires.

Update the context cache using itsttl parameter

The following is an example of a curl command that updates its expiration timeby 3,600 seconds.

Python

Install

pip install --upgrade google-genai

To learn more, see the SDK reference documentation.

Set environment variables to use the Gen AI SDK with Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values# with appropriate values for your project.exportGOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECTexportGOOGLE_CLOUD_LOCATION=globalexportGOOGLE_GENAI_USE_VERTEXAI=True

fromdatetimeimportdatetimeasdtfromdatetimeimporttimezoneastzfromdatetimeimporttimedeltafromgoogleimportgenaifromgoogle.genai.typesimportHttpOptions,UpdateCachedContentConfigclient=genai.Client(http_options=HttpOptions(api_version="v1"))# Get content cache by name# cache_name = "projects/.../locations/.../cachedContents/1111111111111111111"content_cache=client.caches.get(name=cache_name)print("Expire time",content_cache.expire_time)# Example response#   Expire time 2025-02-20 15:50:18.434482+00:00# Update expire time using TTLcontent_cache=client.caches.update(name=cache_name,config=UpdateCachedContentConfig(ttl="36000s"))time_diff=content_cache.expire_time-dt.now(tz.utc)print("Expire time(after update):",content_cache.expire_time)print("Expire time(in seconds):",time_diff.seconds)# Example response#   Expire time(after update): 2025-02-14 01:51:42.571696+00:00#   Expire time(in seconds): 35999# Update expire time using specific time stampnext_week_utc=dt.now(tz.utc)+timedelta(days=7)content_cache=client.caches.update(name=cache_name,config=UpdateCachedContentConfig(expireTime=next_week_utc))print("Expire time(after update):",content_cache.expire_time)# Example response#   Expire time(after update): 2025-02-20 15:51:42.614968+00:00

Go

Learn how to install or update theGo.

To learn more, see the SDK reference documentation.

Set environment variables to use the Gen AI SDK with Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values# with appropriate values for your project.exportGOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECTexportGOOGLE_CLOUD_LOCATION=globalexportGOOGLE_GENAI_USE_VERTEXAI=True

import("context""fmt""io""time"genai"google.golang.org/genai")//updateContentCacheshowshowtoupdatecontentcacheexpirationtime.funcupdateContentCache(wio.Writer,cacheNamestring)error{ctx:=context.Background()client,err:=genai.NewClient(ctx, &genai.ClientConfig{HTTPOptions:genai.HTTPOptions{APIVersion:"v1"},})iferr!=nil{returnfmt.Errorf("failed to create genai client: %w",err)}//UpdateexpiretimeusingTTLresp,err:=client.Caches.Update(ctx,cacheName, &genai.UpdateCachedContentConfig{TTL:time.Duration(time.Duration.Seconds(36000)),})iferr!=nil{returnfmt.Errorf("failed to update content cache exp. time with TTL: %w",err)}fmt.Fprintf(w,"Cache expires in:%s\n",time.Until(resp.ExpireTime))//Exampleresponse://Cacheexpiresin:10h0m0.005875s//UpdateexpiretimeusingspecifictimestampinSevenDays:=time.Now().Add(7*24*time.Hour)resp,err=client.Caches.Update(ctx,cacheName, &genai.UpdateCachedContentConfig{ExpireTime:inSevenDays,})iferr!=nil{returnfmt.Errorf("failed to update content cache expire time: %w",err)}fmt.Fprintf(w,"Cache expires in:%s\n",time.Until(resp.ExpireTime))//Exampleresponse://Cacheexpiresin:167h59m59.80327sreturnnil}

Java

Learn how to install or update theJava.

To learn more, see the SDK reference documentation.

Set environment variables to use the Gen AI SDK with Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values# with appropriate values for your project.exportGOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECTexportGOOGLE_CLOUD_LOCATION=globalexportGOOGLE_GENAI_USE_VERTEXAI=True

importcom.google.genai.Client;importcom.google.genai.types.CachedContent;importcom.google.genai.types.HttpOptions;importcom.google.genai.types.UpdateCachedContentConfig;importjava.time.Duration;importjava.time.Instant;importjava.time.temporal.ChronoUnit;publicclassContentCacheUpdate{publicstaticvoidmain(String[]args){//TODO(developer):Replacethesevariablesbeforerunningthesample.//E.gcacheName="projects/111111111111/locations/global/cachedContents/1111111111111111111"StringcacheName="your-cache-name";contentCacheUpdate(cacheName);}//UpdatesthecacheusingthespecifiedcacheresourcenamepublicstaticvoidcontentCacheUpdate(StringcacheName){//Initializeclientthatwillbeusedtosendrequests.Thisclientonlyneedstobecreated//once,andcanbereusedformultiplerequests.try(Clientclient=Client.builder().location("global").vertexAI(true).httpOptions(HttpOptions.builder().apiVersion("v1").build()).build()){//GetinfoofthecachedcontentCachedContentcachedContent=client.caches.get(cacheName,null);cachedContent.expireTime().ifPresent(expireTime->System.out.println("Expire time: "+expireTime));//Exampleresponse//Expiretime:2025-07-29T23:39:49.227291Z//UpdateexpiretimeusingTTLCachedContentupdatedCachedContent=client.caches.update(cacheName,UpdateCachedContentConfig.builder().ttl(Duration.ofSeconds(36000)).build());updatedCachedContent.expireTime().ifPresent(expireTime->System.out.println("Expire time after update: "+expireTime));//Exampleresponse//Expiretimeafterupdate:2025-07-30T08:40:33.537205Z//UpdateexpiretimeusingspecifictimestampInstantnextWeek=Instant.now().plus(7,ChronoUnit.DAYS);updatedCachedContent=client.caches.update(cacheName,UpdateCachedContentConfig.builder().expireTime(nextWeek).build());updatedCachedContent.expireTime().ifPresent(expireTime->System.out.println("Expire time after update: "+expireTime));//Exampleresponse//Expiretimeafterupdate:2025-08-05T22:40:33.713988900ZSystem.out.println("Updated cache: "+cacheName);}}}

Node.js

Install

npm install @google/genai

To learn more, see the SDK reference documentation.

Set environment variables to use the Gen AI SDK with Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values# with appropriate values for your project.exportGOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECTexportGOOGLE_CLOUD_LOCATION=globalexportGOOGLE_GENAI_USE_VERTEXAI=True

const{GoogleGenAI}=require('@google/genai');const{DateTime}=require('luxon');constGOOGLE_CLOUD_PROJECT=process.env.GOOGLE_CLOUD_PROJECT;constGOOGLE_CLOUD_LOCATION=process.env.GOOGLE_CLOUD_LOCATION||'global';asyncfunctionupdateContentCache(projectId=GOOGLE_CLOUD_PROJECT,location=GOOGLE_CLOUD_LOCATION,cacheName='example-cache'){constclient=newGoogleGenAI({vertexai:true,project:projectId,location:location,httpOptions:{apiVersion:'v1',},});letcontentCache=awaitclient.caches.get({name:cacheName,});console.log('Expire time',contentCache.expireTime);contentCache=awaitclient.caches.update({name:cacheName,config:{ttl:'36000s',},});constexpireTime=DateTime.fromISO(contentCache.expireTime,{zone:'utc'});constnow=DateTime.utc();consttimeDiff=expireTime.diff(now,['seconds']);console.log('Expire time (after update):',expireTime.toISO());console.log('Expire time (in seconds):',Math.floor(timeDiff.seconds));constnextWeekUtc=DateTime.utc().plus({days:7});console.log('Next week (UTC):',nextWeekUtc.toISO());contentCache=awaitclient.caches.update({name:cacheName,config:{expireTime:nextWeekUtc,},});console.log('Expire time (after update):',contentCache.expireTime);returncontentCache;}//Exampleresponse//Expiretime(afterupdate):2025-02-2015:51:42.614968+00:00

REST

You can use REST to create a update the context cache by using the Vertex AI API to send a PATCH request to the publisher model endpoint. The following example shows how to update the expiration date using thettl parameter.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Yourproject ID.
  • LOCATION: The region where the request tocreate the context cache was processed.
  • CACHE_ID: The ID of the context cache. The context cache ID is returned when you create the context cache. You can also find context cache IDs by listing the context caches for a Google Cloud project using. For more information, seecreate a context cache andlist context caches.
  • SECONDS: Afloat that specifies the seconds component of the duration before the cache expires.
  • NANOSECONDS: Afloat that specifies the nanoseconds component of the duration before the cache expires.

HTTP method and URL:

PATCH https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents/CACHE_ID

Request JSON body:

{  "seconds":"SECONDS",  "nanos":"NANOSECONDS"}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

Save the request body in a file namedrequest.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents/CACHE_ID"

PowerShell

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

Save the request body in a file namedrequest.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents/CACHE_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

Response

{  "name": "projects/PROJECT_NUMBER/locations/us-central1/cachedContents/CACHE_ID",  "model": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.0-flash-001",  "createTime": "2024-05-30T21:14:39.880235Z",  "updateTime": "2024-05-31T00:21:15.350969Z",  "expireTime": "2024-05-31T01:21:15.348014Z"}

Example curl command

PROJECT_ID="PROJECT_ID"LOCATION="us-central1"CACHE_ID="CACHE_ID"curl\-XPATCH\-H"Authorization: Bearer$(gcloudauthprint-access-token)"\-H"Content-Type: application/json"\"https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}"-d\'{   "ttl": {"seconds":"3600","nanos":"0"}}'

Update the context cache using itsexpire_time parameter

The following is an example of a curl command that uses theexpire_timeparameter to update its expiration time to 9 AM on June 30, 2024.

REST

You can use REST to create a update the context cache by using the Vertex AI API to send a PATCH request to the publisher model endpoint. The following example shows how to update the expiration date using theexpire_time parameter.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: .
  • LOCATION: The region where the request tocreate the context cache was processed.
  • CACHE_ID: The ID of the context cache. You can find the ID in the response when youcreate the context cache.
  • EXPIRE_TIME: ATimestamp that specifies the time when the context cache expires.

HTTP method and URL:

PATCH https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents/CACHE_ID

Request JSON body:

{   "expire_time":"EXPIRE_TIME"}

To send your request, choose one of these options:

curl

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

Save the request body in a file namedrequest.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents/CACHE_ID"

PowerShell

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

Save the request body in a file namedrequest.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents/CACHE_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

Response

{  "name": "projects/PROJECT_NUMBER/locations/us-central1/cachedContents/CACHE_ID",  "model": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.0-flash-001",  "createTime": "2024-05-30T21:14:39.880235Z",  "updateTime": "2024-05-31T00:20:24.296585Z",  "expireTime": "2024-06-30T09:00:00Z"}

Example curl command

PROJECT_ID="PROJECT_ID"LOCATION="us-central1"CACHE_ID="CACHE_ID"curl\-XPATCH\-H"Authorization: Bearer$(gcloudauthprint-access-token)"\-H"Content-Type: application/json"\"https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}"-d\'{   "expire_time":"2024-06-30T09:00:00.000000Z"}'

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-11-24 UTC.