Get information about a context cache

You can learn about the time a context cache was created, the time it was mostrecently updated, and the time it expires. To get information about everycontext cache associated with a Google Cloud project, including their cache IDs,use the command to list context caches. If you know the cache ID of a contextcache, you can get information about just that context cache.

Get a list of context caches

To get a list of the context caches associated with a Google Cloud project, you needthe region where you created and the ID of your Google Cloud project. The followingshows you how to get a list of context caches for a Google Cloud project.

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

fromgoogleimportgenaifromgoogle.genai.typesimportHttpOptionsclient=genai.Client(http_options=HttpOptions(api_version="v1"))content_cache_list=client.caches.list()# Access individual properties of a ContentCache object(s)forcontent_cacheincontent_cache_list:print(f"Cache `{content_cache.name}` for model `{content_cache.model}`")print(f"Last updated at:{content_cache.update_time}")print(f"Expires at:{content_cache.expire_time}")# Example response:# * Cache `projects/111111111111/locations/.../cachedContents/1111111111111111111` for#       model `projects/111111111111/locations/.../publishers/google/models/gemini-XXX-pro-XXX`# * Last updated at: 2025-02-13 14:46:42.620490+00:00# * CachedContentUsageMetadata(audio_duration_seconds=None, image_count=167, text_count=153, total_token_count=43130, video_duration_seconds=None)# ...

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""net/http""time""google.golang.org/genai")//listContentCacheshowshowtoretrievedetailsaboutcachedcontent.funclistContentCache(wio.Writer)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)}//Retrievecachedcontentmetadatacache,err:=client.Caches.List(ctx, &genai.ListCachedContentsConfig{HTTPOptions: &genai.HTTPOptions{Headers:http.Header{"X-Custom-Header":[]string{"example"}},APIVersion:"v1",},})iferr!=nil{returnfmt.Errorf("failed to get content cache: %w",err)}//Printbasicinfoaboutthecachedcontentfmt.Fprintf(w,"Cache name:%s\n",cache.Name)fmt.Fprintf(w,"Display name:%s\n",cache.Items[0].DisplayName)fmt.Fprintf(w,"Model:%s\n",cache.Items[0].Model)fmt.Fprintf(w,"Create time:%s\n",cache.Items[0].CreateTime.Format(time.RFC3339))fmt.Fprintf(w,"Update time:%s\n",cache.Items[0].UpdateTime.Format(time.RFC3339))fmt.Fprintf(w,"Expire time:%s (in%s)\n",cache.Items[0].ExpireTime.Format(time.RFC3339),time.Until(cache.Items[0].ExpireTime).Round(time.Second))ifcache.Items[0].UsageMetadata!=nil{fmt.Fprintf(w,"Usage metadata: %+v\n",cache.Items[0].UsageMetadata)}//Exampleresponse://Cachename:projects/111111111111/locations/us-central1/cachedContents/1234567890123456789//Displayname:product_recommendations_prompt//Model:models/gemini-2.5-flash//Createtime:2025-04-08T02:15:23Z//Updatetime:2025-04-08T03:05:11Z//Expiretime:2025-04-20T03:05:11Z(in167h59m59s)//Usagemetadata: &{AudioDurationSeconds:0ImageCount:167TextCount:153TotalTokenCount:43124VideoDurationSeconds:0}returnnil}

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.ListCachedContentsConfig;publicclassContentCacheList{publicstaticvoidmain(String[]args){contentCacheList();}//ListsallcachedcontentspublicstaticvoidcontentCacheList(){//Initializeclientthatwillbeusedtosendrequests.Thisclientonlyneedstobecreated//once,andcanbereusedformultiplerequests.try(Clientclient=Client.builder().location("global").vertexAI(true).httpOptions(HttpOptions.builder().apiVersion("v1").build()).build()){for(CachedContentcontent:client.caches.list(ListCachedContentsConfig.builder().build())){content.name().ifPresent(name->System.out.println("Name: "+name));content.model().ifPresent(model->System.out.println("Model: "+model));content.updateTime().ifPresent(time->System.out.println("Last updated at: "+time));content.expireTime().ifPresent(time->System.out.println("Expires at: "+time));}//Exampleresponse://Name:projects/111111111111/locations/global/cachedContents/1111111111111111111//Model://projects/111111111111/locations/global/publishers/google/models/gemini-2.5-flash//Lastupdatedat:2025-07-28T21:54:19.125825Z//Expiresat:2025-08-04T21:54:18.328233500Z//...}}}

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');constGOOGLE_CLOUD_PROJECT=process.env.GOOGLE_CLOUD_PROJECT;constGOOGLE_CLOUD_LOCATION=process.env.GOOGLE_CLOUD_LOCATION||'global';asyncfunctionlistContentCaches(projectId=GOOGLE_CLOUD_PROJECT,location=GOOGLE_CLOUD_LOCATION){constclient=newGoogleGenAI({vertexai:true,project:projectId,location:location,httpOptions:{apiVersion:'v1',},});constcontentCacheList=awaitclient.caches.list();//AccessindividualpropertiesofaContentCacheobject(s)constcontentCacheNames=[];for(constcontentCacheofcontentCacheList.pageInternal){console.log(`Cache\`${contentCache.name}\`formodel\`${contentCache.model}\``);console.log(`Lastupdatedat:${contentCache.updateTime}`);console.log(`Expiresat:${contentCache.expireTime}`);contentCacheNames.push(contentCache.name);}console.log(contentCacheNames);//Exampleresponse://*Cache`projects/111111111111/locations/us-central1/cachedContents/1111111111111111111`for//model`projects/111111111111/locations/us-central1/publishers/google/models/gemini-XXX-pro-XXX`//*Lastupdatedat:2025-02-1314:46:42.620490+00:00//*CachedContentUsageMetadata(audio_duration_seconds=None,image_count=167,text_count=153,total_token_count=43130,video_duration_seconds=None)//...returncontentCacheNames;}

REST

The following shows how to use REST to list the context caches associated with a Google Cloud project by sending a GET request to the publisher model endpoint.

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

HTTP method and URL:

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

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.

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents"

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.

Execute the following command:

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

Response

{  "cachedContents": [    {      "name": "projects/PROJECT_NUMBER/locations/us-central1/cachedContents/CACHE_ID_1",      "model": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-2.0-flash-001",      "createTime": "2024-05-31T19:04:35.380412Z",      "updateTime": "2024-05-31T19:04:35.380412Z",      "expireTime": "2024-05-31T20:04:35.349680Z"    },    {      "name": "projects/PROJECT_NUMBER/locations/us-central1/cachedContents/CACHE_ID_2",      "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"    },    {      "name": "projects/PROJECT_NUMBER/locations/us-central1/cachedContents/CACHE_ID_N",      "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

LOCATION="us-central1"PROJECT_ID="PROJECT_ID"curl\-XGET\-H"Authorization: Bearer$(gcloudauthprint-access-token)"\https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents

Get information about a context cache

To get information about one context cache, you need its cache ID, theGoogle Cloud project ID with which the context cache is associated, and the regionwhere the request tocreate the context cachewas processed. The cache ID of a context cache is returned when you create thecontext cache. You can also get the cache ID of each context cache associatedwith a project using thecontext cache list command.

The following shows you how to get information about one context cache.

Go

Before trying this sample, follow the Go setup instructions in theVertex AI quickstart. For more information, see theVertex AI Go SDK for Gemini reference documentation.

To authenticate to Vertex AI, set up Application Default Credentials. For more information, see Set up ADC for a local development environment.

Streaming and non-streaming responses

You can choose whether the model generatesstreaming responses ornon-streaming responses. For streaming responses, you receive each responseas soon as its output token is generated. For non-streaming responses, you receiveall responses after all of the output tokens are generated.

For a streaming response, use theGenerateContentStream method.

  iter := model.GenerateContentStream(ctx, genai.Text("Tell me a story about a lumberjack and his giant ox. Keep it very short."))

For a non-streaming response, use theGenerateContent method.

  resp, err := model.GenerateContent(ctx, genai.Text("What is the average size of a swallow?"))

Sample code

import("context""fmt""io""cloud.google.com/go/vertexai/genai")// getContextCache shows how to retrieve the metadata of a cached content// contentName is the ID of the cached content to retrievefuncgetContextCache(wio.Writer,contentNamestring,projectID,locationstring)error{// location := "us-central1"ctx:=context.Background()client,err:=genai.NewClient(ctx,projectID,location)iferr!=nil{returnfmt.Errorf("unable to create client: %w",err)}deferclient.Close()cachedContent,err:=client.GetCachedContent(ctx,contentName)iferr!=nil{returnfmt.Errorf("GetCachedContent: %w",err)}fmt.Fprintf(w,"Retrieved cached content %q",cachedContent.Name)returnnil}

REST

The following shows how to use REST to list the context caches associated with a Google Cloud project by sending a GET request to the publisher model endpoint.

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. 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.

HTTP method and URL:

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

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.

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "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.

Execute the following command:

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

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -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-31T19:04:35.380412Z",  "updateTime": "2024-05-31T19:04:35.380412Z",  "expireTime": "2024-05-31T20:04:35.349680Z"}

Example curl command

LOCATION="us-central1"PROJECT_ID="PROJECT_ID"CACHE_ID="CACHE_ID"curl\-XGET\-H"Authorization: Bearer$(gcloudauthprint-access-token)"\https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/${CACHE_ID}

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-12-15 UTC.