class RubyLLM::Cost

A Cost prices token usage in US dollars using pricing from the model registry. Usage entries own accounting events; Message and Chat aggregate calls, and Model#cost_for prices any token usage against a specific model.

response = chat.ask "Summarize Ruby's object model."
response.cost.total

cost = model.cost_for(response.tokens)
cost.input
cost.output

The components are RubyLLM’s normalized token buckets: input, output, cache_read, cache_write, and thinking. When the registry lacks pricing for tokens that were used, the affected component and total return nil instead of a false zero.

When the provider reports the exact cost of a call, total returns the reported amount instead of a registry-price estimate, even when registry pricing is missing.

Costs are computed when the object is built. Readers do not recalculate them when registry prices change. ::aggregate and ::from_h return the same class, so a single call, a whole chat, and a stored breakdown all read the same way.

Public Class Methods

aggregate (costs, complete: true)

Source

# File lib/ruby_llm/cost.rb, line 44
def aggregate(costs, complete: true)
  costs = costs.compact.select(&:tokens?)

  missing = COMPONENTS.select do |component|
    costs.any? { |cost| cost.missing?(component) }
  end

  amounts = COMPONENTS.to_h do |component|
    values = costs.filter_map { |cost| cost.public_send(component) }
    [component, missing.include?(component) || values.empty? ? nil : values.sum]
  end

  new(amounts:, missing:, reported: costs.any?, complete:, total: aggregate_total(costs))
end

Combines several costs into one Cost that sums each component. Ignores nil entries. A component returns nil when pricing was missing for one of the calls, or when no call has a cost for that component. Pass complete: false when some requests are still running or their costs are unknown; total then remains nil.

cost = RubyLLM::Cost.aggregate(messages.map(&:cost))
cost.total

from_h (hash, tokens: nil)

Source

# File lib/ruby_llm/cost.rb, line 70
def from_h(hash, tokens: nil)
  amounts = COMPONENTS.to_h { |component| [component, recorded_amount(hash, component)] }
  total_recorded = hash.key?(:total) || hash.key?('total')
  total = recorded_amount(hash, :total) if total_recorded
  missing = missing_recorded_components(amounts, tokens, total)

  new(amounts:, missing:, reported: recorded_tokens?(amounts, tokens, total_recorded), total:)
end

Rebuilds a cost from a stored breakdown Hash, as produced by to_h and persisted alongside a usage entry. Keys may be Strings or Symbols, and amounts may be numeric Strings, as JSON encodes decimals. The component readers return the recorded amounts and total equals the recorded :total. A breakdown with a total omits the components that had no usage, so ::aggregate still sums them across costs. Pass tokens to mark used components without a recorded amount as missing pricing.

RubyLLM::Cost.from_h({ input: 0.0001, total: 0.0003 }).total

Public Instance Methods

cache_read ()

Source

# File lib/ruby_llm/cost.rb, line 138
def cache_read
  @amounts[:cache_read]
end

Returns the cost of cache-read input tokens in US dollars, or nil when the token count or its pricing is unavailable.

cache_write ()

Source

# File lib/ruby_llm/cost.rb, line 146
def cache_write
  @amounts[:cache_write]
end

Returns the cost of cache-write input tokens in US dollars, or nil when the token count or its pricing is unavailable. Writes with a longer lifetime, reported in Tokens#cache_write_by_ttl, are priced at the provider’s rate for that lifetime.

input ()

Source

# File lib/ruby_llm/cost.rb, line 126
def input
  @amounts[:input]
end

Returns the cost of input tokens in US dollars, or nil when the token count or its pricing is unavailable.

output ()

Source

# File lib/ruby_llm/cost.rb, line 132
def output
  @amounts[:output]
end

Returns the cost of billable output tokens in US dollars, or nil when the token count or its pricing is unavailable.

thinking ()

Source

# File lib/ruby_llm/cost.rb, line 154
def thinking
  @amounts[:thinking]
end

Returns the cost of thinking tokens in US dollars, or nil when the model does not price reasoning output separately from regular output or the token count is unavailable. When not priced separately, thinking tokens are part of output.

to_h ()

Source

# File lib/ruby_llm/cost.rb, line 176
def to_h
  {
    input: input,
    output: output,
    cache_read: cache_read,
    cache_write: cache_write,
    thinking: thinking,
    total: total
  }.compact
end

Returns a hash of component costs in US dollars, plus :total, omitting nil values.

total ()

Source

# File lib/ruby_llm/cost.rb, line 162
def total
  return nil unless @complete
  return nil unless tokens?
  return @total unless @total.nil?
  return nil if @missing.any?

  amounts = @amounts.values.compact
  return nil if amounts.empty?

  amounts.sum
end

Returns the sum of all components in US dollars, or the exact amount the provider reported when it reported one. Returns nil when there is no token usage, or when pricing is missing for tokens that were used and the provider reported no cost.