Skip to content

Docs: Add per-request usage to docs and example script #2026

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 5, 2025
+16 −1
Merged

Docs: Add per-request usage to docs and example script #2026

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ The Agents SDK automatically tracks token usage for every run. You can access it
- **input_tokens**: total input tokens sent
- **output_tokens**: total output tokens received
- **total_tokens**: input + output
- **request_usage_entries**: list of per-request usage breakdowns
- **details**:
- `input_tokens_details.cached_tokens`
- `output_tokens_details.reasoning_tokens`
Expand Down Expand Up @@ -46,6 +47,17 @@ result = await Runner.run(agent, "What's the weather in Tokyo?")
print(result.context_wrapper.usage.total_tokens)
```

## Per-request usage tracking

The SDK automatically tracks usage for each API request in `request_usage_entries`, useful for detailed cost calculation and monitoring context window consumption.

```python
result = await Runner.run(agent, "What's the weather in Tokyo?")

for request in enumerate(result.context_wrapper.usage.request_usage_entries):
print(f"Request {i + 1}: {request.input_tokens} in, {request.output_tokens} out")
```

## Accessing usage with sessions

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.
Expand Down Expand Up @@ -78,5 +90,6 @@ class MyHooks(RunHooks):
For detailed API documentation, see:

- [`Usage`][agents.usage.Usage] - Usage tracking data structure
- [`RequestUsage`][agents.usage.RequestUsage] - Per-request usage details
- [`RunContextWrapper`][agents.run.RunContextWrapper] - Access usage from run context
- [`RunHooks`][agents.run.RunHooks] - Hook into usage tracking lifecycle
4 changes: 3 additions & 1 deletion examples/basic/usage_tracking.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,12 @@ def get_weather(city: str) -> Weather:

def print_usage(usage: Usage) -> None:
print("\n=== Usage ===")
print(f"Requests: {usage.requests}")
print(f"Input tokens: {usage.input_tokens}")
print(f"Output tokens: {usage.output_tokens}")
print(f"Total tokens: {usage.total_tokens}")
print(f"Requests: {usage.requests}")
for i, request in enumerate(usage.request_usage_entries):
print(f" {i + 1}: {request.input_tokens} input, {request.output_tokens} output")


async def main() -> None:
Expand Down