> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.runledger.co/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runledger.co/_mcp/server. # Pricing from cost > **Note** > > 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](/guides/cost-catalog-and-models#the-provider-price-catalog) 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](/guides/cost-catalog-and-models#the-provider-price-catalog), each entry with its source and the date it takes effect, and your own rates layered on top as [overrides](/guides/cost-catalog-and-models#your-own-rates-override-the-catalog) | | 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](/concepts/billing) | 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](/api-reference/how-configuration-works#dry-run) of a configuration change, and [`POST /v1/events/preview`](/guides/cost-attribution-and-margin#preview-a-price), 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 1. **Pick what you pay.** Find each provider model your code calls in the [provider price catalog](/guides/cost-catalog-and-models#the-provider-price-catalog) and create a [cost model](/guides/cost-catalog-and-models#cost-models-and-rate-cards) 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. 2. **Add your own rates.** If you pay less than list, or run a private or self-hosted deployment, add [overrides](/guides/cost-catalog-and-models#your-own-rates-override-the-catalog) or a custom cost model, with the contract or invoice behind them in `reason`. 3. **Say how you price it.** Create a [price rule](/guides/price-rules-and-guardrails#price-rules) and point a plan rate at it. 4. **Set a floor.** Create a [margin guardrail](/guides/price-rules-and-guardrails#margin-guardrails). Start with `warn`. 5. **Simulate.** [Replay](/guides/price-changes-and-simulation#simulation) recent usage against the setup before it goes live. 6. **Apply.** In the sandbox, apply the configuration. For live, propose it and a person approves the diff, as for any [configuration](/api-reference/how-configuration-works#proposals-for-live). 7. **Run.** Call `check()` before the work, `track()` after it, and `trace()` around each model call, all with the same `run_id`. 8. **Read the margin.** `GET /v1/runs/{run_id}` and `GET /v1/reports/margin` show revenue, cost and margin, [after reversals](/guides/cost-attribution-and-margin#margin-after-reversals). 9. **Handle a provider price change.** When a provider changes a price, the catalog [publishes a new version](/guides/price-changes-and-simulation#when-a-provider-changes-its-prices) 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](/agents/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](/api-reference/access-and-audit#keys-and-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: 1. [Catalog, cost models and overrides](/guides/cost-catalog-and-models): choose what you pay. 2. [Price rules and margin guardrails](/guides/price-rules-and-guardrails): set what you charge and the floor. 3. [Cost attribution and margin](/guides/cost-attribution-and-margin): record costs and read the margin. 4. [Provider price changes and simulation](/guides/price-changes-and-simulation): handle a provider change and test before you apply.