---
source: https://iinventedlight.com/library/notes/ao-cost-token-usage-tracking.md
title: "Tracking agent token usage and cached-token savings"
license: CC-BY-4.0
license_url: https://creativecommons.org/licenses/by/4.0/
source_license: "Apache-2.0 or MIT (repo docs; LICENSE file verified in each GitHub repo); prose restates cited source lines in own words"
license_family: agentops-green
attribution: "Summary by iinventedlight (AI-assisted). Sources: OpenAI Agents SDK (Python) docs (GitHub), Usage, MIT (openai/openai-agents-python LICENSE); Google Gemini CLI docs (GitHub), Token caching and cost optimization, Apache-2.0 (google-gemini/gemini-cli LICENSE)."
author: "iinventedlight (synthesis of cited sources); text drafted with AI assistance"
date: 2026-11-09
status: published
checked_on: 2026-11-09
as_of: 2026-11-09
confidence: medium
untested: "No tool or code was run for this note; only the fetched repository documentation was read."
category: agent-operations
topic_area: "agent operations: cost and usage budgeting"
tags: [tokens, usage, openai-agents-sdk, gemini-cli]
client: Librarian
sources:
  - id: S1
    title: "Usage"
    publisher: OpenAI Agents SDK (Python) docs (GitHub)
    url: https://github.com/openai/openai-agents-python/blob/main/docs/usage.md
    accessed: 2026-11-09
    license: "MIT (openai/openai-agents-python LICENSE)"
  - id: S2
    title: "Token caching and cost optimization"
    publisher: Google Gemini CLI docs (GitHub)
    url: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/token-caching.md
    accessed: 2026-11-09
    license: "Apache-2.0 (google-gemini/gemini-cli LICENSE)"
---
# Tracking agent token usage and cached-token savings

**Answer:** The Agents SDK automatically tracks token usage for every run, so you can monitor costs or enforce limits. In Gemini CLI, the `/stats` command shows token usage and cached token savings.

## Agents SDK usage fields

- `requests`: number of LLM API calls made.
- `input_tokens`, `output_tokens`, `total_tokens` (input + output).
- `request_usage_entries`: per-request usage breakdowns.
- Details include `cached_tokens`, `cache_write_tokens`, and `reasoning_tokens`.

After `Runner.run(...)`, access usage via `result.context_wrapper.usage`. Usage is aggregated across all model calls during the run, including calls that produce tool calls or handoffs. With some third-party adapters, usage is not reported by default and needs `ModelSettings(include_usage=True)`.

## Gemini CLI token caching

Token caching reuses previous system instructions and context to reduce the number of tokens processed in later requests. It is available with API key authentication (Gemini API key or Vertex AI), not for OAuth users. Use the `/stats` command to view token usage and cached token savings.

## See also

- [ao-cost-compression-accounting](https://iinventedlight.com/library/notes/ao-cost-compression-accounting/)
- [ao-routing-gemini-cli-fallback](https://iinventedlight.com/library/notes/ao-routing-gemini-cli-fallback/)

## Claims

- id: C1
  claim: The Agents SDK tracks token usage per run.
  source: S1
  evidence: "The Agents SDK automatically tracks token usage for every run."

- id: C2
  claim: Usage aggregates across all model calls in a run.
  source: S1
  evidence: "Usage is aggregated across all model calls during the run"

- id: C3
  claim: Token caching reuses instructions and context.
  source: S2
  evidence: "reuses previous system instructions and context to reduce the number of tokens"

- id: C4
  claim: /stats shows cached token savings.
  source: S2
  evidence: "You can view your token usage and cached token savings using the `/stats` command."

## Sources

- [S1] Usage. OpenAI Agents SDK (Python) docs (GitHub). https://github.com/openai/openai-agents-python/blob/main/docs/usage.md . License: MIT (openai/openai-agents-python LICENSE). Accessed 2026-11-09.

- [S2] Token caching and cost optimization. Google Gemini CLI docs (GitHub). https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/token-caching.md . License: Apache-2.0 (google-gemini/gemini-cli LICENSE). Accessed 2026-11-09.


License: this note is CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Summary by iinventedlight (AI-assisted). Sources: GitHub repository docs under Apache License 2.0 (https://www.apache.org/licenses/LICENSE-2.0) or MIT License (https://opensource.org/licenses/MIT), as listed per source; copyright notices remain with the original authors. Text was condensed and changed from the originals.

---

Agents: [/agents.md](/agents.md) | [/.well-known/agent-library.json](/.well-known/agent-library.json).