RunCost

RunCost Ledger is an auditable LLM API cost calculator for answering one question:

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

It turns provider responses, framework usage objects, or normalized usage into a componentized cost ledger with input, cached input, output, reasoning, tool units, batch results, discounts, dated price sources, and warnings. It runs in Python, JavaScript/TypeScript, Go, the CLI, browsers, and edge runtimes without requiring a proxy or hosted account.

Install

Install from package registries:

pip install runcost-ai
npm install runcost
go get github.com/adamallcock/runcost/packages/go/ledger

Source checkout development paths:

python3 -m pip install git+https://github.com/adamallcock/runcost.git
PKG_TGZ=$(npm pack ./packages/javascript/core --silent)
npm install "./$PKG_TGZ"

The Python distribution name is runcost-ai; the import package and CLI are runcost. The npm package is runcost. The Go package is github.com/adamallcock/runcost/packages/go/ledger.

60-Second Quickstart

The convenience APIs resolve current public pricing from genai-prices, then models.dev, then LiteLLM, and cache the selected source for 24 hours. Pass the response you already receive; RunCost never sends it to a pricing source.

Python:

from runcost import from_response_auto

response = {
    "id": "resp_example",
    "object": "response",
    "model": "gpt-4.1-mini-2025-04-14",
    "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")
print(ledger["total"], ledger["components"], ledger["warnings"])

JavaScript/TypeScript:

import { fromResponseAuto } from "runcost";

const response = {
  id: "resp_example",
  object: "response",
  model: "gpt-4.1-mini-2025-04-14",
  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.components, ledger.warnings);

CLI (Python install or npx runcost):

runcost quote response.json --provider openai
cat batch-results.jsonl | runcost quote - --jsonl --provider openai

Try the same flow without installing anything in the browser playground.

External Price Resolution

Published RunCost packages contain no provider price database. The auto APIs select exactly one upstream catalog per calculation, record attempted-source and cache metadata, and fall back to the next source only when the earlier one cannot price the requested model. OpenRouter-billed responses try OpenRouter's models API first; direct-provider responses do not silently use OpenRouter rates.

Python: resolve_price_catalog(...), from_response_auto(...)

JavaScript/TypeScript: resolvePriceCatalog(...), fromResponseAuto(...)

Go: ResolvePriceCatalog(...), FromResponseAuto(...)

Node, Python, Go, and the CLIs use an OS cache with conditional refresh and a last-known-good fallback. Browser/edge builds use an in-memory cache. Use runcost prices status|refresh|clear to inspect or manage the CLI cache.

Explicit Custom Prices

Explicit cards remain the deterministic, network-free path for negotiated rates, unpublished models, reviewed snapshots, or fully self-contained tests.

Python:

from runcost import from_response

response = {
    "model": "gpt-4.1-mini-2025-04-14",
    "usage": {
        "input_tokens": 36,
        "input_tokens_details": {"cached_tokens": 6},
        "output_tokens": 87,
        "output_tokens_details": {"reasoning_tokens": 12},
    },
}

price_cards = [{
    "schema_version": "0.1",
    "id": "openai:gpt-4.1-mini:example",
    "provider": "openai",
    "surface": "openai.responses",
    "model": "gpt-4.1-mini",
    "aliases": ["gpt-4.1-mini-2025-04-14"],
    "components": [
        {"usage_component": "input_uncached_tokens", "unit": "token", "price": {"amount": "0.40", "currency": "USD", "per": "1000000"}},
        {"usage_component": "input_cache_read_tokens", "unit": "token", "price": {"amount": "0.10", "currency": "USD", "per": "1000000"}},
        {"usage_component": "output_text_tokens", "unit": "token", "price": {"amount": "1.60", "currency": "USD", "per": "1000000"}},
        {"usage_component": "output_reasoning_tokens", "unit": "token", "price": {"amount": "1.60", "currency": "USD", "per": "1000000"}},
    ],
    "source": {"name": "example"},
}]

ledger = from_response(
    response,
    provider="openai",
    surface="openai.responses",
    model="gpt-4.1-mini",
    price_cards=price_cards,
)

print(ledger["total"])
print(ledger["components"])
print(ledger["warnings"])

TypeScript:

import { fromResponse } from "runcost";

// Using the same response and priceCards shape as the Python example above.
const ledger = fromResponse(response, {
  provider: "openai",
  surface: "openai.responses",
  model: "gpt-4.1-mini",
  priceCards
});

console.log(ledger.total);
console.log(ledger.components);
console.log(ledger.warnings);

Go:

package main

import (
    "fmt"

    ledger "github.com/adamallcock/runcost/packages/go/ledger"
)

func main() {
    priceCards := []any{
        ledger.Object{
            "schema_version": "0.1",
            "id":             "openai:gpt-4.1-mini:example",
            "provider":       "openai",
            "surface":        "openai.responses",
            "model":          "gpt-4.1-mini",
            "aliases":        []any{"gpt-4.1-mini-2025-04-14"},
            "components": []any{
                ledger.Object{
                    "usage_component": "input_uncached_tokens",
                    "unit":            "token",
                    "price": ledger.Object{"amount": "0.40", "currency": "USD", "per": "1000000"},
                },
                ledger.Object{
                    "usage_component": "output_text_tokens",
                    "unit":            "token",
                    "price": ledger.Object{"amount": "1.60", "currency": "USD", "per": "1000000"},
                },
            },
            "source": ledger.Object{"name": "example"},
        },
    }

    cost := ledger.FromResponse(
        ledger.Object{
            "model": "gpt-4.1-mini-2025-04-14",
            "usage": ledger.Object{
                "input_tokens":  36,
                "output_tokens": 87,
            },
        },
        ledger.Object{
            "provider": "openai",
            "surface":  "openai.responses",
            "model":    "gpt-4.1-mini",
        },
        priceCards,
        nil,
    )

    fmt.Println(cost["total"])
}

Already have normalized usage? Use the deterministic calculator directly:

from runcost import calculate_cost

ledger = calculate_cost(
    usage_ledger={
        "schema_version": "0.1",
        "provider": "openai",
        "surface": "openai.responses",
        "model": {"requested": "gpt-4.1-mini"},
        "components": [
            {"name": "input_uncached_tokens", "quantity": "30", "unit": "token"},
            {"name": "output_text_tokens", "quantity": "75", "unit": "token"},
        ],
    },
    price_cards=price_cards,
)

Main APIs

Supported Inputs

Fixture-backed surfaces include OpenAI Responses, Chat Completions, Embeddings, Images, and Batch; Anthropic Messages and Message Batches; Gemini Developer and Vertex AI batch/generateContent; AWS Bedrock Converse and model-invocation batch; Kimi and DashScope batch; OpenRouter; Cohere Chat and Rerank, OpenAI-compatible providers such as Meta, Groq, xAI, Mistral, DeepSeek, Azure OpenAI, Hugging Face Inference Providers, Tinker, NVIDIA NIM, AI21, Arcee, DashScope, Inception, Poolside, Xiaomi, ZAI, and MiniMax, plus selected framework objects from LangChain, Vercel AI SDK, OpenAI Agents SDK, LlamaIndex, Haystack, LiteLLM, AutoGen/AG2, LangSmith, Semantic Kernel, and OpenRouter SDK paths.

Anthropic Messages includes generic per-attempt fallback attribution across raw responses, Python SDK objects, and final streaming events. Ledgers expose the requested, attempted, serving, and pricing models; Message Batch refusals remain visible as successful provider results that require a separate retry.

See supported surfaces for the current matrix.

Custom Prices And Discounts

RunCost treats provider pricing as data. You can pass user price cards for private rates, exact aliases, service tiers, long-context prices, historical effective dates, tool units, or internal billing units.

discounts = [{
    "schema_version": "0.1",
    "id": "openai-contract-4pct",
    "match": {"provider": "openai"},
    "adjustment": {"type": "percentage_discount", "value": "4"},
}]

The returned ledger records selected price sources, applied discounts, and any warning that prevents the total from being fully explained.

Fixtures are behavioral conformance tests, not a complete model-price database. Use the external resolver, a caller-owned reviewed source-cache snapshot, or explicit contract cards; see price data strategy.

Python:

from runcost import from_response_auto

ledger = from_response_auto(
    response,
    provider="openai",
    surface="openai.responses",
    model="gpt-4.1-mini",
    sources=["genai-prices", "models.dev", "litellm"],
)

TypeScript:

import { fromResponseAuto } from "runcost";

const ledger = await fromResponseAuto(response, {
  provider: "openai",
  surface: "openai.responses",
  model: "gpt-4.1-mini",
  sources: ["genai-prices", "models.dev", "litellm"]
});

Warnings

RunCost is designed to be boring. When it cannot confidently price something, it returns a structured warning such as unknown_model, component_unpriced, price_stale, stream_usage_missing, or provider_reported_cost_mismatch. Use strict mode in tests or reconciliation flows when warnings should fail.

CLI

The Python and npm packages install equivalent quote CLIs:

runcost quote response.json --provider openai
runcost quote - --jsonl --provider openai < responses.jsonl
runcost price-cards --source-type user-pricing --input prices.json
runcost fixture-check fixtures/my-case.json
npx runcost quote response.json --provider openai

Read Next

• Quickstart
• Product expansion quickstart
• External fixture contributions
• Send a billing edge case that calculators get wrong
• Integration case-study template
• Package installation
• Migration from hand-written formulas
• API reference
• Supported surfaces
• Custom pricing and discounts
• Source adapters
• Price data strategy
• Aggregation and streaming
• Warnings and limitations
• Contributing
• Security
• Changelog

Status

RunCost 0.2.x is public beta. The strict live-smoke, release, and real dashboard-comparison gates pass, and the core behavior is fixture-backed across Python, JavaScript/TypeScript, and Go. The public conformance report inventories 202 cases without claiming unsupported behavior. Packages are published to PyPI, npm, and Go module tags. Use provider-reported costs, exports, or dashboard reconciliation before treating any independent calculation as invoice-exact.