From 5e4f6de39562f361c2ee4ba950d4bbcae0027b77 Mon Sep 17 00:00:00 2001
From: Google Team Member <genai-sdk-bot@google.com>
Date: Sun, 26 Apr 2026 21:14:54 -0700
Subject: [PATCH] feat(interaction-api): Implementation of adding grounding
 tool usage breakdown to Interaction Usage.

FUTURE_COPYBARA_INTEGRATE_REVIEW=https://github.com/googleapis/python-genai/pull/2345 from MukundaKatta:fix/retry-httpx-timeout 9b2d886a2b25e01700f8f998b100517ac9569527
PiperOrigin-RevId: 906115416
---
 google/genai/_interactions/types/usage.py       | 14 ++++++++++++++
 google/genai/_interactions/types/usage_param.py | 14 ++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/google/genai/_interactions/types/usage.py b/google/genai/_interactions/types/usage.py
index 61cf506a6..c10bf3a9e 100644
--- a/google/genai/_interactions/types/usage.py
+++ b/google/genai/_interactions/types/usage.py
@@ -23,6 +23,7 @@
 __all__ = [
     "Usage",
     "CachedTokensByModality",
+    "GroundingToolCount",
     "InputTokensByModality",
     "OutputTokensByModality",
     "ToolUseTokensByModality",
@@ -39,6 +40,16 @@ class CachedTokensByModality(BaseModel):
     """Number of tokens for the modality."""
 
 
+class GroundingToolCount(BaseModel):
+    """The number of grounding tool counts."""
+
+    count: Optional[int] = None
+    """The number of grounding tool counts."""
+
+    type: Optional[Literal["google_search", "google_maps", "retrieval"]] = None
+    """The grounding tool type associated with the count."""
+
+
 class InputTokensByModality(BaseModel):
     """The token count for a single response modality."""
 
@@ -75,6 +86,9 @@ class Usage(BaseModel):
     cached_tokens_by_modality: Optional[List[CachedTokensByModality]] = None
     """A breakdown of cached token usage by modality."""
 
+    grounding_tool_count: Optional[List[GroundingToolCount]] = None
+    """Grounding tool count."""
+
     input_tokens_by_modality: Optional[List[InputTokensByModality]] = None
     """A breakdown of input token usage by modality."""
 
diff --git a/google/genai/_interactions/types/usage_param.py b/google/genai/_interactions/types/usage_param.py
index b2806aae5..7f20157eb 100644
--- a/google/genai/_interactions/types/usage_param.py
+++ b/google/genai/_interactions/types/usage_param.py
@@ -23,6 +23,7 @@
 __all__ = [
     "UsageParam",
     "CachedTokensByModality",
+    "GroundingToolCount",
     "InputTokensByModality",
     "OutputTokensByModality",
     "ToolUseTokensByModality",
@@ -39,6 +40,16 @@ class CachedTokensByModality(TypedDict, total=False):
     """Number of tokens for the modality."""
 
 
+class GroundingToolCount(TypedDict, total=False):
+    """The number of grounding tool counts."""
+
+    count: int
+    """The number of grounding tool counts."""
+
+    type: Literal["google_search", "google_maps", "retrieval"]
+    """The grounding tool type associated with the count."""
+
+
 class InputTokensByModality(TypedDict, total=False):
     """The token count for a single response modality."""
 
@@ -75,6 +86,9 @@ class UsageParam(TypedDict, total=False):
     cached_tokens_by_modality: Iterable[CachedTokensByModality]
     """A breakdown of cached token usage by modality."""
 
+    grounding_tool_count: Iterable[GroundingToolCount]
+    """Grounding tool count."""
+
     input_tokens_by_modality: Iterable[InputTokensByModality]
     """A breakdown of input token usage by modality."""