class RubyLLM::Tokens
A Tokens holds normalized token counts for a provider attempt, a response, or an aggregate. Read them from Chat#tokens, Message#tokens, Chunk#tokens, and individual operation results such as Embedding. Counts the provider did not report are nil.
response = chat.ask "What is the capital of France?" response.tokens.input # standard input tokens response.tokens.output # billable output tokens response.tokens.cache_read # prompt cache reads response.tokens.cache_write # prompt cache writes
Attributes
The number of tokens served from the provider’s prompt cache, or nil if the provider did not report it.
The number of tokens written to the provider’s prompt cache, or nil if the provider did not report it.
The tokens in cache_write split by cache lifetime, as a Hash of the TTL Strings that with_caching(ttl:) accepts and Integer counts, or nil if the provider did not report a split. Lifetimes with no writes are left out. Providers that price a longer lifetime higher, such as Anthropic’s one-hour cache, use it to price cache_write.
response.tokens.cache_write_by_ttl # => {"5m" => 1024, "1h" => 2048}
The number of standard (non-cached) input tokens, or nil if the provider did not report it.
The number of billable output tokens, or nil if the provider did not report it. Includes thinking tokens when the provider bills them as output.
The exact cost of the call in US dollars as reported by the provider, or nil if the provider does not report one. When present, Cost#total returns it instead of a registry-price estimate.
How many times each provider-executed tool ran, as a Hash of String keys and Integer counts, or nil if the provider reported none. Web searches are "web_search_requests" on every provider that reports them. Other tools follow the same form, such as "web_fetch_requests" and "code_execution_requests". Tools that did not run are left out. Providers bill these per use, not in tokens.
response.tokens.server_tool_use # => {"web_search_requests" => 2}
The number of thinking (reasoning) tokens, or nil if the provider does not report them.
Public Class Methods
Source
# File lib/ruby_llm/tokens.rb, line 96 def self.aggregate(tokens) tokens = Array(tokens).compact return tokens.first if tokens.one? values = %i[input output cache_read cache_write thinking reported_cost].to_h do |component| reported = tokens.filter_map { |usage| usage.public_send(component) } [component, reported.empty? ? nil : reported.sum] end new(**values, cache_write_by_ttl: aggregate_counts(tokens, :cache_write_by_ttl), server_tool_use: aggregate_counts(tokens, :server_tool_use)) end
Sums token counts across provider attempts. A bucket remains nil when no attempt reported it.
# File lib/ruby_llm/tokens.rb, line 82 def initialize(input: nil, output: nil, cache_read: nil, cache_write: nil, thinking: nil, cache_write_by_ttl: nil, server_tool_use: nil, reported_cost: nil) @input = input @output = output @cache_read = cache_read @cache_write = cache_write @thinking = thinking @cache_write_by_ttl = positive_counts(cache_write_by_ttl) @server_tool_use = positive_counts(server_tool_use) @reported_cost = reported_cost end
Creates token counts from the supplied values. Omitted counts remain nil; zero means a reported count of zero. Returns a Tokens object even when every count is nil.
tokens = RubyLLM::Tokens.new(input: 100, output: 20) RubyLLM.models.find("gpt-6.1-sol").cost_for(tokens).total
cache_write_by_ttl: splits the cache writes by lifetime, keyed as cache_write_by_ttl describes; server_tool_use: counts the provider-executed tools that ran, keyed as server_tool_use describes; reported_cost: holds the provider’s total price in US dollars.
Public Instance Methods
Source
# File lib/ruby_llm/tokens.rb, line 137 def to_h { input_tokens: input, output_tokens: output, cache_read_tokens: cache_read, cache_write_tokens: cache_write, thinking_tokens: thinking, cache_write_tokens_by_ttl: cache_write_by_ttl, server_tool_use: server_tool_use }.compact end
Returns the counts as a hash with keys :input_tokens, :output_tokens, :cache_read_tokens, :cache_write_tokens, and :thinking_tokens, omitting nil counts. Includes :cache_write_tokens_by_ttl and :server_tool_use when reported. The provider’s reported cost is available separately through reported_cost.
response.tokens.to_h # => {input_tokens: 14, output_tokens: 5}