From 5a19298931d31f24c58ee0dcd725a359cb1a7746 Mon Sep 17 00:00:00 2001
From: habema <abualhaj02@gmail.com>
Date: Tue, 2 Sep 2025 14:58:39 +0300
Subject: [PATCH] clarify usage metrics in sessions and add API reference
 section

---
 docs/usage.md | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/docs/usage.md b/docs/usage.md
index fc0fae9e2..4f0a66309 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -30,25 +30,35 @@ Usage is aggregated across all model calls during the run (including tool calls
 
 ## Accessing usage with sessions
 
-When you use a `Session` (e.g., `SQLiteSession`), usage continues to accumulate across turns within the same run. Each call to `Runner.run(...)` returns the run’s cumulative usage at that point.
+When you use a `Session` (e.g., `SQLiteSession`), each call to `Runner.run(...)` returns usage for that specific run. Sessions maintain conversation history for context, but each run's usage is independent.
 
 ```python
 session = SQLiteSession("my_conversation")
 
 first = await Runner.run(agent, "Hi!", session=session)
-print(first.context_wrapper.usage.total_tokens)
+print(first.context_wrapper.usage.total_tokens)  # Usage for first run
 
 second = await Runner.run(agent, "Can you elaborate?", session=session)
-print(second.context_wrapper.usage.total_tokens)  # includes both turns
+print(second.context_wrapper.usage.total_tokens)  # Usage for second run
 ```
 
+Note that while sessions preserve conversation context between runs, the usage metrics returned by each `Runner.run()` call represent only that particular execution. In sessions, previous messages may be re-fed as input to each run, which affects the input token count in consequent turns.
+
 ## Using usage in hooks
 
-If you’re using `RunHooks`, the `context` object passed to each hook contains `usage`. This lets you log usage at key lifecycle moments.
+If you're using `RunHooks`, the `context` object passed to each hook contains `usage`. This lets you log usage at key lifecycle moments.
 
 ```python
 class MyHooks(RunHooks):
     async def on_agent_end(self, context: RunContextWrapper, agent: Agent, output: Any) -> None:
         u = context.usage
         print(f"{agent.name} → {u.requests} requests, {u.total_tokens} total tokens")
-```
\ No newline at end of file
+```
+
+## API Reference
+
+For detailed API documentation, see:
+
+-   [`Usage`][agents.usage.Usage] - Usage tracking data structure
+-   [`RunContextWrapper`][agents.run.RunContextWrapper] - Access usage from run context
+-   [`RunHooks`][agents.run.RunHooks] - Hook into usage tracking lifecycle
\ No newline at end of file