# How pricing works

> The Markdown form of https://openfill.ai/docs/pricing. The index of every docs page is https://openfill.ai/llms.txt, and every page in one file is https://openfill.ai/llms-full.txt.

You are charged the clearing level at execution, up to the price you set. Every request to a market model sets one; the last section covers fixed-price models. A request that does not run costs nothing.

## The level

Each market model has one clearing level: a price in USD per 1M input tokens at the reference mix (90% cached, 2% output). The market sets it. On every tick the engine admits the orders at the top of the book while the pods have room, and a demand curve built from waiting and running requests sets the target price. The published level moves toward that target. Spare capacity can bring the target to 0; execution is free when the published level reaches 0.

The published level walks toward that price in bounded steps rather than jumping, and it rises more slowly than it falls. `GET /v1/market` answers with the level and the instant it last moved; the [market page](https://openfill.ai/market) draws it.

## Your price limit

Every request to a market model names the most it will pay, in the level's unit. A price limit is a ceiling on what you pay rather than a condition of being served: on every tick the market admits from the top of the book while the pods have room, so a request at or above the level normally runs at once, and one below it waits while capacity is short and runs as soon as there is room, until your timeout, or until you cancel. Whenever it runs you are charged the level at that moment, up to your price limit.

The first of these that is set wins:

1. `price_limit` in the request body (use `extra_body` with the OpenAI SDK)
2. The `X-Price-Limit` header
3. The API key's own price limit (set on [Bidding](https://openfill.ai/bidding))
4. Your account default for that model (set on [Bidding](https://openfill.ai/bidding))

> Caution
>
> A request to a market model that sets *none* of the four above is rejected with `400`, whether or not its price is locked. An account default satisfies it, so a request carrying no `price_limit` at all still runs when one is configured. Defaults are per model: a default for one market says nothing about another.

A price limit is a price cap, per token, on one request. It bounds nothing about how much you spend over a day; your prepaid balance does that, and [auto-recharge](https://openfill.ai/billing) is off unless you turn it on.

Buy credit at face value on the [billing page](https://openfill.ai/billing). Extra credit grows 1% each time the amount doubles, from 1% at $25 to 10% at $12,800 in one purchase. A 5% card processing fee is added. For a purchase above the billing page's maximum, email [support@openfill.ai](mailto:support@openfill.ai).

## What you pay

One rule: the charge is the lower of the level at execution and the price your request rested at. A price limit above the level buys a place higher in the book and changes nothing about what you pay. Every completion carries the receipt in `usage.x_market`; on a stream it arrives in the final usage chunk, which is sent only when the request carries `stream_options: {"include_usage": true}`.

| Field | Meaning |
| --- | --- |
| order_id | The order the request ran as, which every /v1/orders route takes. |
| level_at_execution | The price the request was charged at: the lower of the level and the bid, in the price limit's unit. On a fixed-price model, its prices at the reference mix, in the same unit. |
| bid | What the request rested at: your price limit, or the lower of the quote and your price limit when the price was locked. On a fixed-price model, the same figure as level_at_execution. |
| charged_usd | The debit, in USD to nine decimal places. 0 at a level of 0. |
| pricing | market, or fixed on a fixed-price model. Absent on a result stored before the field existed, which reads as market. |
| usd_per_million | On a fixed-price model only: the three prices applied, per 1M tokens of cache-hit input, cache-miss input and output. |

### Never charged

- A request to a market model that waits past its timeout, which answers 408.
- A request to a fixed-price model that does not start before its timeout, which answers 429.
- A request to a fixed-price model that was still queued when that model's prices changed.
- A request you cancel while it is queued.
- A price-locked request that misses its execute window, which answers 429.
- A request the backend fails, which answers 502 or 503, or 400 when the backend rejected the request itself.
- A request refused before it enters the book: 400, 401, 402, 403, 404, 409, 413, 429, 503.
- A retry carrying the same Idempotency-Key while the original is running or done, which returns the original outcome. After an expiry, a failure or a cancel the key is released and the retry is a new request, charged as one.

### What is promised, and what is left to the market

| Promised | Left to the market |
| --- | --- |
| On a market model, you are never charged more than your price limit. | When a request executes. |
| On a market model, you are charged the lower of the level and your bid at execution. | Whether it executes before your timeout. |
| Nothing that did not execute is charged. | The level at execution. A lock caps what you pay at the quote; it does not fix the level. |
| A request is never refused on price. | Throughput and latency once it runs. |
| A locked request starts within its window or cancels free. | That an idle market stays idle. |

## The unit

Token pricing on a market model is a 1:10:20 ratio of cache-hit to cache-miss to output, so a miss costs 10 times a hit and output costs 2 times a miss.

Whether a token is a hit or a miss is decided at execution.

Live figures: GET https://api.openfill.ai/v1/market/levels for every level, and GET https://api.openfill.ai/v1/market?model= for one level with its per-token prices.

**Why 1M input tokens costs exactly the level**

The level is quoted per 1M input tokens at a reference mix of 90% cache-hit and 10% cache-miss, with output at 2% of input. Weighting that mix by a model's token ratio gives its divisor, 2.3 here, chosen so a typical well-cached workload of 1M input tokens costs exactly the published level. A workload with a worse cache ratio costs more, and a better one costs less.

## A worked clearing

Suppose `market-preview` is clearing at **$0.2500** and you send a request with a price limit of **$0.4000**: 10,000 prompt tokens, of which 9,000 are served from cache, and 200 output tokens.

Suppose capacity is available and the request starts at that level. It is charged the level, shared across the three token kinds by the model's ratio.

| Tokens | Count | Cost |
| --- | --- | --- |
| Cache-hit input | 9,000 | $0.000978 |
| Cache-miss input | 1,000 | $0.001087 |
| Output | 200 | $0.000435 |
| **Charged** |  | **$0.0025** |

**usage.x_market**

```json
{
  "order_id": "<order_id>",
  "pricing": "market",
  "level_at_execution": 0.25,
  "bid": 0.4,
  "charged_usd": 0.0025
}
```

At your price limit the same request would have cost $0.004. The difference is what the price limit is for: a ceiling you set, with the level underneath it.

Send the same request with a price limit of **$0.1000** while the level is $0.2500 and it ranks below every request at $0.2500, so it waits while the pods are full. When capacity reaches it, it runs and is charged the lower of the level and $0.1000. If the level reaches 0 first, it runs free. If your timeout passes first, it expires and costs nothing.

## Against what you know

|  | A rate card | Spot instances | OpenFill |
| --- | --- | --- | --- |
| The price | Fixed per model, printed once. | Set by the cloud and moved slowly. | The level: set by the market, moving with load, 0 when idle. |
| A price below the current one | Cannot be offered. | The request stays open until the price falls. | The request waits in the book, ranked by price, until there is room for it. |
| What you pay | The printed price. | The spot price in effect, up to your maximum. | The level at execution, up to your price limit. |
| Interruption | None. | The instance can be reclaimed while running. | None on price. A request that has started is never reclaimed for a higher bid, and a generation the backend fails is not charged. |
| Where you read the price | A price list. | A console chart. | GET /v1/market, the streams, and the charts on every market page. |

The OpenFill column is a market model. The last section covers fixed-price models.

## Waiting and timeouts

An unlocked request to a market model waits at most `max_wait` seconds, 10 seconds to 30 days, and then expires with `408` and no charge; one to a fixed-price model ends with `429 capacity_unavailable` instead, as the last section says. Set your SDK's own timeout above that plus the time a generation takes, or the client gives up on a request that is still in the book and would have run. The [orders page](https://openfill.ai/docs/orders#waiting) covers the wait, cancelling, and repricing a queued request.

To know the price before you send, and only then, lock it: the [price lock](https://openfill.ai/docs/price-lock) bids the lower of the published quote and your price limit, and starts within a short window or cancels free. An unlocked request keeps its place in the book, so the lock is for requests that have to be priced in advance.

## Pricing a request before you send it

`GET /v1/market` answers with the level and the same figure as the three per-token prices it implies, so a client can estimate a request from its own token counts.

```bash
curl "https://api.openfill.ai/v1/market?model=market-preview"
```

**Response**

```json
{"model": "market-preview", "level": 0.023,
 "usd_per_million": {"cached": 0.01, "uncached": 0.1, "output": 0.2},
 "mode": "clearing", "degraded": false, "updated_at": "..."}
```

## Fixed-price models

Some models are sold at a fixed price instead: three published prices per 1M tokens, one each for cache-hit input, cache-miss input and output. The figures are on the [models page](https://openfill.ai/docs/models#fixed-price) and under `pricing` on `GET /v1/models`, and the market endpoints answer such a model with `400 fixed_price_model`.

An executed request to a fixed-price model is charged its measured tokens of each kind at the prices published when it was submitted; a batch line takes the prices standing when its batch was created. A price limit or a price lock sent with it has no effect, so a tool that sends one `X-Price-Limit` for every model can keep it, and such a request never answers `missing_price_limit`. A default price limit for the model cannot be set.

It waits for a free slot, and for enough balance to cover it at those prices, for up to its order timeout or its `max_wait`. The requests waiting for one model take turns across accounts; within an account, interactive requests go first, with one batch line after every 4. One that does not start in time ends with `429 capacity_unavailable` and no charge. A request still queued when the model's prices change is not run and not charged, and a batch line whose model's prices changed after the batch was created is not run either.

The balance check sizes a request at those prices, so its `402` says the fixed prices rather than the current level. The receipt carries `pricing: "fixed"` and the prices applied as `usd_per_million`; `bid` and `level_at_execution` both hold those prices at the reference mix, and `charged_usd` is the sum of each kind's tokens times its price.

Previous: [Integrations](https://openfill.ai/docs/integrations). Next: [Price lock](https://openfill.ai/docs/price-lock).