Billing

The SDK bills two ways. In token mode, the default, it sends token counts and your Lago plan turns them into money. In price mode, it looks up the per-token price of the model, multiplies by the tokens used, applies your markup, and sends the dollar cost. Both modes ship the same normalized usage. The difference is only where the arithmetic happens.

Which mode do you want

Pick token mode when	Pick price mode when
You bill in your own units — credits, requests, seats — and tokens are just the input	You resell LLM access at a margin and want the dollar cost to follow the rate card automatically
You want billing to be independent of any third-party price source	You want your revenue to track your provider invoice without maintaining a price table
Your workload is audio-heavy or very long-context (see Known limits)	Your workload is text, and the models you use are in the price sources
You use Bedrock Claude, Databricks or Snowflake Cortex, which the SDK always bills in tokens	You want the cost broken down by token type on the invoice

You can also mix: set one mode globally and override per call with extra_lago={"mode": "price"} in Python or lago: { mode: "price" } in TypeScript.

from lago_agent_sdk import LagoConfig, LagoSDK

sdk = LagoSDK(
    api_key="<YOUR_LAGO_API_KEY>",
    default_subscription_id="sub_acme",
    config=LagoConfig(
        api_key="<YOUR_LAGO_API_KEY>",
        pricing_mode="price",   # "tokens" (default) | "price"
        markup=1.2,             # optional. 1.2 = +20%
    ),
)

import { LagoSDK } from "lago-agent-sdk";

const sdk = new LagoSDK({
  apiKey: process.env.LAGO_API_KEY!,
  defaultSubscriptionId: "sub_acme",
  config: {
    pricingMode: "price", // "tokens" (default) | "price"
    markup: 1.2,          // optional. 1.2 = +20%
  },
});

Token mode

The SDK emits one event per non-zero field. A field with no metric code is not emitted at all, so trimming metric_codes down to what you actually bill on is a legitimate way to cut event volume.

Canonical field	Default metric code	What it counts
`input`	`llm_input_tokens`	Total prompt tokens
`output`	`llm_output_tokens`	Total completion tokens
`cache_read`	`llm_cached_input_tokens`	Prompt tokens served from cache
`cache_write`	`llm_cache_creation_tokens`	Prompt tokens written to cache
`cache_write_5m`	`llm_cache_write_5m_tokens`	Cache writes at the 5-minute TTL (Anthropic)
`cache_write_1h`	`llm_cache_write_1h_tokens`	Cache writes at the 1-hour TTL (Anthropic)
`reasoning`	`llm_reasoning_tokens`	Thinking tokens (OpenAI o-series, Gemini 2.5)
`tool_calls`	`llm_tool_calls`	Tool invocations in the response
`image_input`	`llm_image_input_tokens`	Image tokens in the prompt (Gemini)
`audio_input`	`llm_audio_input_tokens`	Audio tokens in the prompt (OpenAI, Gemini)
`audio_output`	`llm_audio_output_tokens`	Audio tokens in the response (OpenAI, Gemini)

Register each one you plan to bill on as a sum_agg billable metric on field_name: "value". Every event also carries model, provider, and api in its properties, so you can build filter-based charges without passing anything extra.

Subsets and additive fields

This is the one thing to get right, and it is the source of most mis-billing. Some fields are breakdowns inside another field. Some are additions to it. Summing a subset into its parent double-counts; forgetting to add an additive field under-counts.

Field	Relationship	Providers
`cache_read`	subset of `input`	OpenAI, Gemini, Mistral, Workers AI
`cache_read`	additive to `input`	Anthropic (native and Bedrock)
`cache_write`	additive to `input`	Anthropic
`audio_input`, `image_input`	subset of `input`	OpenAI, Gemini
`audio_output`	subset of `output`	OpenAI, Gemini
`reasoning`	subset of `output`	OpenAI
`reasoning`	additive to `output`	Gemini

So llm_input_tokens is already your total prompt count on OpenAI and Gemini, but on Anthropic your true total is llm_input_tokens + llm_cached_input_tokens + llm_cache_creation_tokens.

The setup that gets this right

Rather than reasoning about it per provider, bill the parent fields at your standard rate and use the subset fields only to discount, with a provider filter to separate the two rules. For a mixed OpenAI / Anthropic / Gemini estate:

Charge	Metric	Filter	Why
Standard input	`llm_input_tokens`	none	The prompt total on every provider
Cached input discount	`llm_cached_input_tokens`	`provider != anthropic`	Already inside `llm_input_tokens`, so charge a negative or reduced-rate adjustment, never an addition
Anthropic cached input	`llm_cached_input_tokens`	`provider = anthropic`	Additive — charge it at Anthropic’s cache-read rate
Anthropic cache writes	`llm_cache_creation_tokens`	`provider = anthropic`	Additive — charge at the premium cache-creation rate
Standard output	`llm_output_tokens`	none	Completion total on every provider
Gemini reasoning	`llm_reasoning_tokens`	`provider = gemini`	Additive on Gemini only. Do not add it on OpenAI

See Charges with filters for the filter syntax.

The two mistakes that cost real money: billing llm_input_tokens + llm_cached_input_tokens on OpenAI or Gemini (double-counts the cached portion), and billing llm_output_tokens alone on Gemini (misses the thinking tokens you are already paying Google for).

Price mode resolves all of this for you — it applies the correct per-field prices itself, so none of the above has to be encoded in your plan.

Price mode

Where prices come from

OpenRouter’s public model list for native OpenAI, Anthropic, Mistral, and Gemini clients. No credentials.
The AWS Bedrock Price List Bulk API for Bedrock, parsed per region. No credentials.
Cloudflare’s own model catalog for Workers AI. Needs a Cloudflare account id and API token — see Cloudflare AI Gateway.
Ramp Router’s own model catalog for calls through Router: the rates Router bills, rather than a public listing. The catalog is account-scoped, and wrap() reads the Router key from the client you pass in — see Ramp Router.

Tables refresh in the background on the queue thread, so your LLM call is never slowed down waiting on a price. Prices are keyed off the model that answered, not the one you asked for. Providers resolve short aliases to dated snapshots server-side (claude-sonnet-4-5 becomes claude-sonnet-4-5-20250929, Mistral’s -latest and Gemini’s aliases hot-swap the same way), and OpenRouter lists the snapshot. The adapters read the model off the response and fall back to the requested id only when the response is silent about it.

What it emits

One llm_cost event per priced token type, each carrying precise_total_amount_cents at the top level plus token_type, unit (tokens of that type), value (cost after markup), base_cost (before markup), unit_price, markup, price_source, model, provider, and api in properties. The exception is a cost the SDK did not compute. When a gateway reports its own metered cost per call and you pass it through, there is no per-field split to report, so that path emits a single event with no token_type.

Lago setup for price mode. Register a sum_agg billable metric llm_cost on field_name: "unit" and attach a dynamic charge to it. Lago sums each event’s precise_total_amount_cents into a single fee, and unit is the displayed usage quantity.Group the charge by ["model", "token_type"] so one metric breaks the cost down by both dimensions.

Markup

Set markup to resell at a profit — 1.2 means the customer pays your cost plus 20%. It applies per priced field, and both the pre-markup base_cost and post-markup value land on every event so the margin stays auditable. Override it for one call with extra_lago={"markup": 1.5}.

Known limits

Price mode prices five fields: input, output, cache_read, cache_write, and reasoning. Tool calls carry no unit price, so they produce no cost event — meter those in token mode if you bill on them. The 5-minute / 1-hour cache-write splits are priced separately only where the price source publishes a rate for each, which today is Ramp Router; everywhere else the whole cache_write count bills at the single write rate. Audio and image tokens are priced at the text rate. They sit inside input/output, so they are billed, but at the model’s text price rather than its modality price. Providers often charge considerably more for audio. If your workload is audio-heavy, bill it in token mode using llm_audio_input_tokens and llm_audio_output_tokens and set your own rate. Long-context and service-tier rates are not modelled. Some providers raise the per-token rate above a context threshold, and discount batch or flex tiers. The SDK prices everything at the model’s base rate. The exception is Ramp Router, where the response names the tier it was served at: a non-default tier there is a reported price miss rather than a base-rate charge. See Ramp Router. A price miss never drops usage. If the table has not warmed up on the very first call, or the model is missing from the source, the SDK falls back to token-count events and reports a PricingUnavailableError through on_error. It never bills zero and never drops the call.

If you have configured only the llm_cost metric and a price lookup misses, the fallback token events have nowhere to land and that usage goes unbilled. Register the token metrics alongside llm_cost even when you bill in price mode.

Databricks-hosted models are always billed as token counts, even in price mode. Their provider name is deliberately unmatched against the price sources, because the open-weight models Databricks hosts are listed elsewhere at a fraction of what Databricks charges. The SDK logs this once per model at info level rather than reporting an error. See Databricks. Snowflake Cortex is always billed as token counts, on both its REST and AI SQL function surfaces. Snowflake meters Cortex in credits at a per-credit rate that depends on edition, region and contract, published in no API and no view, so there is no rate card to look up and no later refresh that could supply one. A price-mode caller still gets token events for these rows, with no price-miss error, because a structural absence of a rate card is not a lookup failure. See Snowflake Cortex. Ramp Router is priced from Router’s own catalog, at the default tier. Router publishes per-model rates in GET /v1/models for your account, and those are the rates it bills on every vendor it fronts. A call served at a non-default tier, or through a backend whose rate the catalog does not publish, falls back to token events with a PricingUnavailableError that says why. See Ramp Router. AWS’s public bulk price data omits the current Claude models. It lists Titan, Llama, Mistral, Cohere and older Claude, but at time of writing not Claude 3.5/3.7/4. Bedrock calls for those fall back to token events. Native Anthropic clients are priced through OpenRouter and unaffected.

Custom metric codes

If your Lago tenant already uses different codes, override them at init:

from lago_agent_sdk import LagoConfig, LagoSDK

sdk = LagoSDK(
    api_key="<YOUR_LAGO_API_KEY>",
    config=LagoConfig(
        api_key="<YOUR_LAGO_API_KEY>",
        metric_codes={
            "input": "ai_input_tokens",
            "output": "ai_output_tokens",
        },
    ),
)

import { LagoSDK } from "lago-agent-sdk";

new LagoSDK({
  apiKey: process.env.LAGO_API_KEY!,
  config: {
    metricCodes: {
      input: "ai_input_tokens",
      output: "ai_output_tokens",
    },
  },
});

Next steps

Configuration reference

Every config knob, error type, and the emit() escape hatch.

Charges with filters

Price cache reads and cache writes at different rates.

Introduction

Get started

Events & Usage Components

Pricing & Subscriptions

Quotes & Order Forms

Invoicing

Payments & Cash Collection

AI Agents and MCP

Data & Analytics

Revenue recognition

Resources

Which mode do you want

Token mode

Subsets and additive fields

The setup that gets this right

Price mode

Where prices come from

What it emits

Markup

Known limits

Custom metric codes

Next steps

Configuration reference

Charges with filters

​Which mode do you want

​Token mode

​Subsets and additive fields

​The setup that gets this right

​Price mode

​Where prices come from

​What it emits

​Markup

​Known limits

​Custom metric codes

​Next steps

Configuration reference

Charges with filters

Which mode do you want

Token mode

Subsets and additive fields

The setup that gets this right

Price mode

Where prices come from

What it emits

Markup

Known limits

Custom metric codes

Next steps