Token usage and cost

Aggregates the usage rows of sessions (children included, each request counted once) and, for x = NULL, of every live session of this process plus the process System 1 log. Reads only.

Usage

gptr_usage(
  x = NULL,
  by = c("session", "agent", "model", "route"),
  detail = FALSE
)

Arguments

x

A gptr_session, a list of sessions, or NULL (every live session of this process and the System 1 log).

by

Grouping of the summary: "session", "agent", "model" or "route".

detail

FALSE: a gptr_usage data frame (group, requests, input, output, cache_read, cache_write, cost) with attribute totals; TRUE: the gptr_ledger per request and context component (request_id, component, tokens, cached) of the sessions' own requests, session by session in request order (a child's requests are in the child's ledger).

Value

A gptr_usage or gptr_ledger data frame.

Details

Unknown usage stays unknown: a token count or cost that a provider did not report is NA, never zero, so a group or total that includes it is NA and the footer prints it as unknown. A known zero, such as the metered charge of a local model, stays zero. Rows without a session, agent, model or route (process-level System 1 calls) form the NA group.

The detailed component ledger contains estimates; its sum can differ from provider-reported usage. A run's token budget checks estimated next-input tokens and recorded usage before requests; cost limits check recorded cost. The next output or an unknown final charge can exceed a remaining allowance, so these stopping policies are not billing reservations. Teams and fan-outs count child requests against their shared root budget.

Examples

gptr_usage()
#>   group        requests  input  output  cache_read  cache_write  cost
#> 1 s5a87880424  1         1631   1       0           0            0
#> 2 s73215d9152  1         1630   2       0           0            0
#> 3 s821e7f6633  4         6483   14      0           0            0
#> 4 s90798930dd  1         1633   3       0           0            0
#> 5 sa7b5e3174d  1         1631   1       0           0            0
#> 6 NA           1         91     20      0           0            0
#> 
#> # 6 rows
#> 9 requests, 13.1k tokens in, $0.0000
session = peter("hi", model = gptr_fake_provider(list("hello")))
#> gptr: thinking
#> gptr: done · 1 turn · 1.6k tokens · $0.0000
gptr_usage(session)
#>   group        requests  input  output  cache_read  cache_write  cost
#> 1 s1770ca856f  1         1630   2       0           0            0
#> 
#> # 1 row
#> 1 request, 1.6k tokens in, $0.0000