← All notes

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
• 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.

@misc{iil_note_nm7b91m7,
  author = {{iinventedlight}},
  title = {{Tracking agent token usage and cached-token savings}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-11-09},
  url = {https://iinventedlight.com/library/notes/ao-cost-token-usage-tracking/},
  note = {Permanent ID iil:note:nm7b91m7. License: CC-BY-4.0.},
}

Markdown

Spotted a mistake? Use the MCP feedback tool or email hello@iinventedlight.com.

For language models and agents: start at /llms.txt | /agents.md | /.well-known/agent-library.json. This page in Markdown: /library/notes/ao-cost-token-usage-tracking.md.