diff --git a/docs/edge/en/concepts/crews.mdx b/docs/edge/en/concepts/crews.mdx
index 2c43b63c7..5bed8495b 100644
--- a/docs/edge/en/concepts/crews.mdx
+++ b/docs/edge/en/concepts/crews.mdx
@@ -322,6 +322,8 @@ Caches can be employed to store the results of tools' execution, making the proc
 
 After the crew execution, you can access the `usage_metrics` attribute to view the language model (LLM) usage metrics for all tasks executed by the crew. This provides insights into operational efficiency and areas for improvement.
 
+`total_tokens` is the billed total (`prompt_tokens + completion_tokens`). Breakdown fields such as `cached_prompt_tokens` describe subsets already included in those totals — see [Flow Usage Metrics](/concepts/flows#flow-usage-metrics) for the full field semantics.
+
 ```python Code
 # Access the crew's usage metrics
 crew = Crew(agents=[agent1, agent2], tasks=[task1, task2])
diff --git a/docs/edge/en/concepts/flows.mdx b/docs/edge/en/concepts/flows.mdx
index 647512545..38a1eb282 100644
--- a/docs/edge/en/concepts/flows.mdx
+++ b/docs/edge/en/concepts/flows.mdx
@@ -267,7 +267,24 @@ print(flow.usage_metrics)
   execution.
 </Note>
 
-Each entry in the returned [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) is the sum across all LLM calls made within a single `flow.kickoff()` invocation. Counters reset on the next `kickoff()` call (or on each iteration of `kickoff_for_each`), so successive runs don't double-count. The property is safe to read at any point after `kickoff()` completes; reading it during execution returns the partial total accumulated so far.
+### UsageMetrics field semantics
+
+The returned [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) object uses a provider-neutral contract:
+
+| Field | Meaning |
+| --- | --- |
+| `total_tokens` | Billed total: `prompt_tokens + completion_tokens` |
+| `prompt_tokens` | Full input/prompt tokens billed for the request |
+| `completion_tokens` | Output/completion tokens billed for the request |
+| `cached_prompt_tokens` | Cache-read subset of prompt tokens (breakdown only) |
+| `reasoning_tokens` | Reasoning/thinking subset where the provider reports it separately (breakdown only) |
+| `successful_requests` | Number of LLM calls aggregated |
+
+Breakdown fields such as `cached_prompt_tokens` and `reasoning_tokens` are **not** added on top of `total_tokens` — they describe portions already included in `prompt_tokens` or `completion_tokens`.
+
+For Anthropic, cache read and cache write counters are folded into `prompt_tokens`, so cached workloads are fully reflected in `total_tokens`. OpenAI-style providers already include cached input inside `prompt_tokens`; CrewAI surfaces the cached portion separately for visibility.
+
+Each entry in the returned `UsageMetrics` is the sum across all LLM calls made within a single `flow.kickoff()` invocation. Counters reset on the next `kickoff()` call (or on each iteration of `kickoff_for_each`), so successive runs don't double-count. The property is safe to read at any point after `kickoff()` completes; reading it during execution returns the partial total accumulated so far.
 
 ## Flow State Management