llm_usage: Summarize token usage and outcomes of an LLM run

In LLMR: Interface for Large Language Model APIs in R

Summarize token usage and outcomes of an LLM run

Description

Reads the diagnostic columns produced by call_llm_par() (and call_llm_broadcast() / llm_fn() with .return = "columns") or by llm_mutate(), and returns a one-row tibble of counts and token totals. It reports tokens, not money: sent, received, total, and reasoning tokens are summed with na.rm = TRUE (correct under row batching, which attributes a batch's tokens to its first row and leaves the rest NA). To estimate cost, multiply these by your provider's current per-token prices yourself.

Usage

llm_usage(x, prefix = NULL, price_table = NULL)

Arguments

x	A data frame from call_llm_par() or llm_mutate().
prefix	For an llm_mutate() result, the output column name whose diagnostics to summarize (e.g. "answer"). Inferred automatically when a single diagnostic block is present; required when several are.
price_table	Optional data frame you supply with your provider's current prices, holding columns model, input, and output (US dollars per million tokens), and optionally cached (price per million cached prompt tokens). When given, a cost_estimate column is added: cached tokens are billed at the cached rate (or the input rate if no cached column), the remaining sent tokens at input, and received tokens at output. LLMR ships no price list on purpose; prices change, and a stale bundled table would mislead silently.

Value

A one-row tibble: n, n_ok, n_failed, ok_rate, n_truncated (finish "length"), n_filtered (finish "filter"), sent_tokens, rec_tokens, total_tokens, reasoning_tokens, cached_tokens (prompt tokens served from the provider's cache, when reported), n_unknown_tokens (successful rows for which the provider reported no token usage, so the token sums above understate the truth), duration_s, (when a batch id column is present) rowpack_calls and rows_per_rowpack, and (when price_table is supplied) cost_estimate in the table's currency.

See Also

llm_failures(), llm_preview(), llm_par_resume().

Examples

res <- tibble::tibble(
  success = c(TRUE, TRUE, FALSE),
  finish_reason = c("stop", "length", "error:rate_limit"),
  sent_tokens = c(10L, 12L, NA_integer_),
  rec_tokens = c(5L, 7L, NA_integer_),
  total_tokens = c(15L, 19L, NA_integer_),
  reasoning_tokens = c(NA_integer_, NA_integer_, NA_integer_),
  duration = c(0.4, 0.5, 0.1)
)
llm_usage(res)

LLMR documentation built on July 11, 2026, 1:06 a.m.