TypeScript API: Usage and cost

Tokens and an estimated price for a run. Generated from the declarations and doc comments of criogenai 0.1.7. See also: TypeScript API overview, the same module in Python.

import { ModelUse, RunFacts, Price, estimateCost } from "criogenai";

Contents#

ModelUse#

interface ModelUse {
  provider: string;
  model: string;
  calls: number;
  usage: Record<string, number>;
}

One model used in a run.

Fields

• provider (string): The provider, e.g. "openai" ("fake" for a FakeModel).
• model (string): The model name the provider reported.
• calls (number): Model calls this run made to it.
• usage (Record<string, number>): Tokens: input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, reasoning_tokens.

RunFacts#

interface RunFacts {
  durationMs: number;
  answeredBy: { provider: string; model: string } | null;
  models: ModelUse[];
}

Facts added to every result.

Fields

• durationMs (number): Wall time of the call, in milliseconds.
• answeredBy ({ provider: string; model: string; } | null): The provider and model that wrote the last answer (a fallback shows here).
• models (ModelUse[]): Each model this run called, in first-use order.

Price#

interface Price {
  input: number;
  output: number;
  cacheRead?: number;
}

USD per million tokens.

Fields

• input (number): USD per million input tokens.
• output (number): USD per million output tokens (reasoning tokens included).
• cacheRead (number, optional): Cached input tokens (default: the input price).

estimateCost#

function estimateCost(result: Pick<RunFacts, "models">, prices: Record<string, Price>): number | null

The cost of a run in USD from your prices, keyed by "provider:model" or by model name. null when a model that was used has no price. Reasoning tokens are counted as output tokens.

CriogenAI ships no price list: prices change too often. Put in your provider's current prices.

Parameters

• result (Pick<RunFacts, "models">): A run result or reply (anything with models).
• prices (Record<string, Price>): USD per million tokens, keyed by "provider:model" (checked first) or by model name.

Returns: The estimated cost in USD, or null if a used model has no price.

Example

import { Agent, estimateCost } from "criogenai";

const result = await new Agent({ model: "openai:gpt-5-mini" }).run("Hello");
// Example prices: use your provider's current ones.
const usd = estimateCost(result, { "openai:gpt-5-mini": { input: 0.25, output: 2 } });
console.log(usd === null ? "no price for a model" : `$${usd.toFixed(4)}`);