Pricing from cost | Runledger API

Every amount in the examples is illustrative, and so are the providers (Vidlab, Textco) and the catalog entries shown: none is a real provider price. The freshness targets in the catalog guide are a commitment about how quickly the catalog follows providers, not an accuracy guarantee and not a service-credit SLA.

What an AI product costs to serve depends on the model, the provider and what the customer asked for. A video clip costs more at 1080p than at 720p. A chat answer costs what its input and output tokens cost. A self-hosted model costs GPU seconds. A flat price per event hides all of that, so a price that is right for one request loses money on the next.

Runledger keeps a catalog of provider and model prices, so you pick a model instead of building rate tables. You can layer your own negotiated or self-hosted rates on top, record costs in their own units, price from them, and warn or stop work whose margin falls below a floor. Everything here extends calls you already make. check(), track() and trace() keep their shape, and the added fields are optional, so you can stop at any step and keep what you have.

What each part does

Part	Without pricing from cost	With it
Provider prices	None. `trace()` takes a cost you send	A Runledger-maintained, read-only, versioned provider price catalog, each entry with its source and the date it takes effect, and your own rates layered on top as overrides
Cost capture	`trace()` records provider, model, token counts and a cost you send or Runledger works out	Usage in other units, such as images, video seconds and GPU seconds, with the dimensions that set the rate, priced from your cost models
Price	A flat rate per event or per outcome on a plan	Price rules: cost plus a markup, a table by dimension, or a formula, with a floor and a cap
Margin	Reported per run and per range: confirmed revenue minus cost	Guardrails that warn, or block in `check()`, when work would fall below a floor
Changing rates	A plan’s rates are fixed once it has a subscription	Versioned rate cards, catalog updates that arrive as new rate cards, and a policy for what happens to your prices when a provider changes its own
What if	A dry run of a configuration change, and `POST /v1/events/preview`, which can price an event with any rule	Simulation: replay recorded events and costs against a candidate

The pieces

Object	ID prefix	What it is
Catalog model	`catm_`	A provider model in the Runledger-maintained price catalog, with the units and dimensions it is priced in. Read-only
Catalog price	`catp_`	One version of a catalog model’s rates, with its source, the date it was read and the date it takes effect. Never changes once published
Cost model	`cm_`	What you pay for one provider’s model: the units it is metered in and the dimensions that change its rate. Its `source` is `catalog` (follows a catalog model, with your overrides) or `custom` (your own rate cards)
Rate card	`rc_`	One version of a cost model’s rates, with the date it takes effect. Active cards never change, and a new version must start after every earlier one and can’t start in the past. For a catalog cost model, Runledger creates one for each catalog price
Override	key	Your own rate for a catalog cost model: a discount, or a replacement rate, for some units or dimensions, with optional dates
Price rule	`pr_`	How the price of a usage event is worked out. A plan rate points at one
Margin guardrail	`mg_`	A margin floor for some of your work, with an action: `warn` or `block`
Simulation	`sim_`	A replay of past events and costs against a candidate, with the margin it would have had

Runledger supplies provider prices: you pick a model from the catalog and the rates come with it, each version recording the as_of date and where the rates were read. Your own rates always win over the catalog, and a provider or model the catalog doesn’t have gets a custom cost model with rates you enter.

Who controls a variable

Every unit and dimension in a cost model says who decides its value. The difference decides when Runledger can price it.

	Customer-controlled	Provider-controlled
Examples	Resolution, quality, seconds of video asked for, number of reference images	Input and output tokens, GPU seconds, the context size a prompt ends up at
Known	Before the work starts, from the request	Only after the work, from the provider’s response or your infrastructure
Reaches Runledger as	`properties` on `check()` and `track()`, and `dimensions` on usage lines	`trace()`, after each call
`check()` can	Price it exactly	Estimate it from `estimated_usage`, or from the average cost of recent work of the same kind

So customer price rules should use customer-controlled values, which are known when the price is set. Provider-controlled values show up in cost, and a margin guardrail is how you find out when they have moved the margin.

The workflow

Pick what you pay. Find each provider model your code calls in the provider price catalog and create a cost model from it with catalog_model. No rates to enter. For a model the catalog doesn’t have, create a custom cost model with its own rate card.
Add your own rates. If you pay less than list, or run a private or self-hosted deployment, add overrides or a custom cost model, with the contract or invoice behind them in reason.
Say how you price it. Create a price rule and point a plan rate at it.
Set a floor. Create a margin guardrail. Start with warn.
Simulate. Replay recent usage against the setup before it goes live.
Apply. In the sandbox, apply the configuration. For live, propose it and a person approves the diff, as for any configuration.
Run. Call check() before the work, track() after it, and trace() around each model call, all with the same run_id.
Read the margin. GET /v1/runs/{run_id} and GET /v1/reports/margin show revenue, cost and margin, after reversals.
Handle a provider price change. When a provider changes a price, the catalog publishes a new version and your cost model gets a scheduled rate card. Read what it touches, and decide whether your prices follow.

Cost models, overrides, price rules and guardrails are configuration. They can be set from the dashboard, from the API and from a coding agent over MCP, with the same fields, validation and result. In the dashboard they sit in the Pricing group, with the provider catalog, rate cards and simulations, and the forms share the Preview changes button.

Access

To	Scope
Read the provider price catalog, cost models, rate cards, price rules, guardrails	`config:read`
Write cost models (with overrides), rate cards, rules and guardrails in the sandbox. The catalog itself can’t be written	`config:write`
Propose them for live	`config:propose`
Send usage lines with `trace()`	`events:write`
Run or read a simulation	`config:read` and `events:read`

These are the standard scopes. Pricing from cost adds no scope of its own.

Limits

A commitment ledger: tracking your spend against a committed-spend agreement, or changing a rate automatically when you pass a threshold. Overrides record the rate you pay.
Currency conversion. A catalog price is in the currency the provider quotes, and Runledger doesn’t convert it. A price rule’s currency must match its rate cards and the plans that use it, and each currency is shown separately in reports and simulations, never converted or summed.
Service credits, refunds or an accuracy guarantee for the catalog. The freshness target is a target for how quickly the catalog follows providers, not a promise that a price is correct.
Provider prices fetched from a customer’s own provider account or invoice, and reconciling recorded cost against a provider’s invoice.
Adapters for particular gateways, and a gateway or proxy of Runledger’s own.
Changing a customer’s price mid-period as costs move, and tiers across a customer’s usage over a period.
Price rules for outcome charges. They keep a fixed price.

Next steps

Work through the guides in this order:

Catalog, cost models and overrides: choose what you pay.
Price rules and margin guardrails: set what you charge and the floor.
Cost attribution and margin: record costs and read the margin.
Provider price changes and simulation: handle a provider change and test before you apply.