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

cache_read [R]

The number of tokens served from the provider’s prompt cache, or nil if the provider did not report it.

cache_write [R]

The number of tokens written to the provider’s prompt cache, or nil if the provider did not report it.

input [R]

The number of standard (non-cached) input tokens, or nil if the provider did not report it.

output [R]

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.

reported_cost [R]

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.

server_tool_use [R]

The provider’s server-tool usage counters as a Hash, such as {"web_search_requests" => 2}, or nil if the provider did not report any. Counters are provider-shaped and billed per use, not in tokens.

thinking [R]

The number of thinking (reasoning) tokens, or nil if the provider does not report them.

Public Class Methods

aggregate (tokens)

Source

# File lib/ruby_llm/tokens.rb, line 72
def self.aggregate(tokens)
  tokens = Array(tokens).compact
  return new if tokens.empty?
  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, server_tool_use: aggregate_server_tool_use(tokens))
end

Sums token counts across provider attempts. A bucket remains nil when no attempt reported it.

new (input: nil, output: nil, cache_read: nil, cache_write: nil, thinking: nil, server_tool_use: nil, reported_cost: nil)

Source

# File lib/ruby_llm/tokens.rb, line 59
def initialize(input: nil, output: nil, cache_read: nil, cache_write: nil, thinking: nil,
               server_tool_use: nil, reported_cost: nil)
  @input = input
  @output = output
  @cache_read = cache_read
  @cache_write = cache_write
  @thinking = thinking
  @server_tool_use = 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-5.6").cost_for(tokens).total

server_tool_use: holds provider tool-usage counters; reported_cost: holds the provider’s total price in US dollars.

Public Instance Methods

to_h ()

Source

# File lib/ruby_llm/tokens.rb, line 103
def to_h
  {
    input_tokens: input,
    output_tokens: output,
    cache_read_tokens: cache_read,
    cache_write_tokens: cache_write,
    thinking_tokens: thinking,
    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 :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}