Trace a model call
Records the model, tokens and cost of one model call, so Runledger can report cost and margin per run. Leave out cost and Runledger prices the call from its model price table, including cache and reasoning tokens. Join calls made in different processes by sending the same run_id. Deduplicated on idempotency_key for 35 days. Send usage_lines for units other than tokens, such as images, video seconds, audio seconds or GPU seconds, each with the dimension values that set its rate. When an active cost model matches the call’s provider and model, Runledger prices every line from its rate card (priced_by: catalog), applies any override of the cost model, and records which version and which source priced it. Send usage, usage_lines, or both for different units. If there is no cost model but the provider price catalog has the model, the call is priced from the catalog’s list price (priced_by: price_table) with the warning catalog_model_available, which names the catalog model to adopt so your own rates apply. With neither, the call is recorded without a cost (priced_by: none).
Authentication
A secret key (rl_sk_test_..., rl_sk_live_...) or a restricted key with limited scopes (rl_rk_test_..., rl_rk_live_...). A restricted key can carry agent: true and an expires_at, and is what a coding agent should hold. Keys end in a checksum so secret scanners can recognize them. People create, roll and revoke keys in the dashboard; GET /v1/api_keys lists them, masked.
Request
Quantities of any unit, with the dimension values that decide each rate. A unit can’t appear both here and in usage.
An amount of money that can hold fractions of a minor unit, such as a per-token cost.
Response
request: you sent the cost. price_table: Runledger priced it from the provider price catalog’s list price, because the catalog has the model and no cost model follows it. catalog: Runledger priced it from your cost models, whether their rates come from the provider price catalog, your overrides or rate cards you entered. none: nothing could price it, and the call carries no cost.
The cost of the call. Left out when the call could not be priced: no cost was sent, no cost model or catalog model matched, or no line matched a rate. The warnings say why.
For example rate_not_found when a usage line matched no rate.