RunCost

Provider response in. Itemized USD cost ledger out.

RunCost turns the LLM or agent response you already receive into a local, auditable cost estimate. It separates cached input, uncached input, output, reasoning, tools, media, tiers, batches, and discounts, then records the rates, sources, assumptions, and warnings behind the total.

No proxy, hosted account, or usage database is required.

What did this LLM or agent API call cost, and why?

Try the browser playground or get a first result below.

First Success: Python

The Python distribution is runcost-ai. The import package and installed CLI are both runcost.

pip install runcost-ai

from runcost import from_response_auto

response = {
    "id": "resp_example",
    "object": "response",
    "model": "gpt-4.1-mini",
    "usage": {
        "input_tokens": 36,
        "input_tokens_details": {"cached_tokens": 6},
        "output_tokens": 87,
        "output_tokens_details": {"reasoning_tokens": 12},
    },
}

ledger = from_response_auto(response, provider="openai")

for component in ledger["components"]:
    print(component["name"], component["quantity"], component["cost"])
print("total", ledger["total"], ledger["currency"])
print("source", ledger["price_sources"][0]["name"])
print("warnings", ledger["warnings"])

The result is a structured ledger, not just a number:

input_uncached_tokens    30   0.000012
input_cache_read_tokens   6   0.0000006
output_text_tokens       75   0.00012
output_reasoning_tokens  12   0.0000192
total 0.0001518 USD

This is example output using rates selected on 2026-08-08. Auto-selected public rates can change; the ledger records the source and exact rates used for each calculation.

The selected source is recorded alongside the result. RunCost downloads public pricing data, but never sends your response or usage data to the pricing source.

JavaScript And TypeScript

npm install runcost

import { fromResponseAuto } from "runcost";

const response = {
  id: "resp_example",
  object: "response",
  model: "gpt-4.1-mini",
  usage: {
    input_tokens: 36,
    input_tokens_details: { cached_tokens: 6 },
    output_tokens: 87,
    output_tokens_details: { reasoning_tokens: 12 }
  }
};

const ledger = await fromResponseAuto(response, { provider: "openai" });
console.log(ledger.total, ledger.currency);
console.table(ledger.components);
console.log(ledger.price_sources, ledger.warnings);

The npm package includes TypeScript declarations and an equivalent CLI:

npx runcost quote response.json --provider openai

CLI And Go

The Python CLI prices one JSON response or a JSONL stream:

runcost quote response.json --provider openai
runcost quote - --jsonl --provider openai < responses.jsonl

The Go implementation uses the same shared conformance fixtures:

go get github.com/adamallcock/runcost/packages/go/ledger

See the multi-language quickstart for Go and explicit-price examples.

When To Use RunCost

Use RunCost when you need to:

• Explain a total as separate billing components instead of tokens × rate.
• Keep pricing provenance, effective dates, assumptions, and warnings with the result.
• Reconcile an independent estimate against provider-reported cost or an export.
• Use the same ledger contract in Python, JavaScript/TypeScript, Go, a CLI, or a browser.
• Run locally without placing a proxy or telemetry service in the request path.

RunCost is probably unnecessary when a rough input/output estimate is enough, or when an existing gateway or observability platform already provides the billing record you trust.

How Pricing Works

Published RunCost packages contain no provider price database. The auto APIs select one upstream catalog—normally genai-prices, models.dev, or LiteLLM— cache it, and record the selected source. OpenRouter-billed responses try OpenRouter first; direct-provider responses do not silently use OpenRouter rates.

Pass explicit price cards for negotiated rates, historical snapshots, or network-free tests. See the Price data strategy and custom pricing guide.

RunCost currently calculates USD ledgers only. Arithmetic is deterministic; the estimate is only as accurate as the response fields and selected rates. Reconcile with provider-reported costs, exports, or invoices before treating a result as invoice-exact.

Fixtures are behavioral conformance tests, not a complete model-price database.

Main APIs

Batch APIs, OpenTelemetry GenAI spans, framework adapters, budgets, streaming, discounts, and debug traces are also supported. Browse the API reference or supported surfaces instead of starting with the full surface area.

Custom Prices And Discounts

Use caller-owned price cards for private contracts, exact aliases, service tiers, long-context rates, historical dates, tool units, or self-contained tests. Use discount policies for explicit adjustments that should remain visible as ledger entries. The custom pricing guide contains complete Python, JavaScript, and Go examples.

Warnings

RunCost preserves uncertainty rather than hiding it. Unknown models, unpriced components, stale sources, ambiguous usage, missing stream usage, and provider-reported cost mismatches appear as structured warnings. Use strict mode when those conditions should fail a test or reconciliation workflow.

See warnings and limitations.

Bring RunCost Into A Project

• Replace a hand-written formula with the migration guide.
• Add one sanitized real-world case through the external fixture guide.
• Share a billing edge case that ordinary calculators mishandle in issue #57.
• Start with the quickstart, then browse the documentation index.

Status

RunCost 0.2.x is public beta and published on PyPI, npm, and the Go module proxy. Python, JavaScript/TypeScript, and Go are checked against shared fixtures; the generated conformance report is the source of truth for the current case count and pathway status.

Contributing · Security · Changelog · MIT License