Model Costs

Turn token usage into a RubyLLM::Cost object and aggregate costs across a conversation

After reading this guide, you will know:

  • How to turn a token usage payload into a RubyLLM::Cost object with cost_for.
  • What normalized token buckets RubyLLM prices and exposes.
  • How to read totals from messages, chats, and agents.
  • How to aggregate several cost objects with RubyLLM::Cost.aggregate.
  • When a cost returns nil because pricing is incomplete.

Calculating Costs

Once a model is in the registry, RubyLLM can turn token usage into a RubyLLM::Cost object so you can attach a dollar figure to any response.

model = RubyLLM.models.find('gpt-5-nano')
response = RubyLLM.chat(model: model.id, provider: model.provider).ask("Summarize Ruby's object model.")

cost = model.cost_for(response.tokens)
puts cost.input
puts cost.output
puts cost.cache_read
puts cost.cache_write
puts cost.thinking
puts cost.total

Costs use RubyLLM’s normalized token buckets: standard input, billable output, cache read, cache write, and separately priced thinking when the model registry exposes a distinct reasoning-token price. See Token Usage and Cost for the provider comparison table and what RubyLLM exposes consistently across providers.

Most applications use the shorter helpers on messages, chats, and agents:

response.cost.total
chat.cost.total
agent.cost.total

To combine several cost objects yourself, use RubyLLM::Cost.aggregate:

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

If pricing is incomplete for tokens that were used, the affected cost and cost.total return nil. Cost helpers cover token-priced conversation usage; provider-specific add-ons such as search-query charges remain available in the provider’s raw usage payload.

Next Steps