feat(ai): implicit caching feature (#9462)

hsubox76 · web-flow · commit 2e74329868f9 · 2026-01-29T11:22:11.000-08:00
diff --git a/.changeset/tender-items-pretend.md b/.changeset/tender-items-pretend.md
@@ -0,0 +1,6 @@
+---
+'@firebase/ai': minor
+'firebase': minor
+---
+
+Add params on `UsageMetadata` that provide cache-related usage data when the implicit caching feature is used.
diff --git a/common/api-review/ai.api.md b/common/api-review/ai.api.md
@@ -1444,6 +1444,8 @@ export type URLRetrievalStatus = (typeof URLRetrievalStatus)[keyof typeof URLRet
 
 // @public
 export interface UsageMetadata {
+    cachedContentTokenCount?: number;
+    cacheTokensDetails?: ModalityTokenCount[];
     // (undocumented)
     candidatesTokenCount: number;
     // (undocumented)
diff --git a/docs-devsite/ai.usagemetadata.md b/docs-devsite/ai.usagemetadata.md
@@ -22,6 +22,8 @@ export interface UsageMetadata
 
 |  Property | Type | Description |
 |  --- | --- | --- |
+|  [cachedContentTokenCount](./ai.usagemetadata.md#usagemetadatacachedcontenttokencount) | number | The number of tokens in the prompt that were served from the cache. If implicit caching is not active or no content was cached, this will be 0. |
+|  [cacheTokensDetails](./ai.usagemetadata.md#usagemetadatacachetokensdetails) | [ModalityTokenCount](./ai.modalitytokencount.md#modalitytokencount_interface)<!-- -->\[\] | Detailed breakdown of the cached tokens by modality (for example, text or image). This list provides granular insight into which parts of the content were cached. |
 |  [candidatesTokenCount](./ai.usagemetadata.md#usagemetadatacandidatestokencount) | number |  |
 |  [candidatesTokensDetails](./ai.usagemetadata.md#usagemetadatacandidatestokensdetails) | [ModalityTokenCount](./ai.modalitytokencount.md#modalitytokencount_interface)<!-- -->\[\] |  |
 |  [promptTokenCount](./ai.usagemetadata.md#usagemetadataprompttokencount) | number |  |
@@ -31,6 +33,26 @@ export interface UsageMetadata
 |  [toolUsePromptTokensDetails](./ai.usagemetadata.md#usagemetadatatooluseprompttokensdetails) | [ModalityTokenCount](./ai.modalitytokencount.md#modalitytokencount_interface)<!-- -->\[\] | A list of tokens used by tools, broken down by modality. |
 |  [totalTokenCount](./ai.usagemetadata.md#usagemetadatatotaltokencount) | number |  |
 
+## UsageMetadata.cachedContentTokenCount
+
+The number of tokens in the prompt that were served from the cache. If implicit caching is not active or no content was cached, this will be 0.
+
+<b>Signature:</b>
+
+```typescript
+cachedContentTokenCount?: number;
+```
+
+## UsageMetadata.cacheTokensDetails
+
+Detailed breakdown of the cached tokens by modality (for example, text or image). This list provides granular insight into which parts of the content were cached.
+
+<b>Signature:</b>
+
+```typescript
+cacheTokensDetails?: ModalityTokenCount[];
+```
+
 ## UsageMetadata.candidatesTokenCount
 
 <b>Signature:</b>
diff --git a/packages/ai/src/types/responses.ts b/packages/ai/src/types/responses.ts
@@ -133,6 +133,18 @@ export interface UsageMetadata {
    * A list of tokens used by tools, broken down by modality.
    */
   toolUsePromptTokensDetails?: ModalityTokenCount[];
+  /**
+   * The number of tokens in the prompt that were served from the cache.
+   * If implicit caching is not active or no content was cached,
+   * this will be 0.
+   */
+  cachedContentTokenCount?: number;
+  /**
+   * Detailed breakdown of the cached tokens by modality (for example, text or
+   * image). This list provides granular insight into which parts of
+   * the content were cached.
+   */
+  cacheTokensDetails?: ModalityTokenCount[];
 }
 
 /**
