Before a run
Every tool has one price description: its base rate and unit in dollars, plus the input fields, minimums, rounding and add-ons that change the calculation. It isprice_description on Inspect a model, with
your organization’s fee, and the console’s Pricing page lists them all.
duration 10 at $0.07 per second is $0.70. The names in backticks are the run’s own input
fields. A sentence that starts with “About” or “Up to”, or says the final charge comes from usage, gives a typical cost or
a ceiling: the tool is priced by what it uses, which is only known after the run. price_description is null for a
tool that has no price yet.
To price one exact input, send it to Estimate a run (MCP estimate_cost). It answers
the amount a run of that input would hold, without starting it, and whether that amount is exact, a maximum or
approximate. The input is checked as a run’s is, so an estimate that answers 200 is an input the run accepts.
During and after a run
When a run starts, its estimate is held from your balance (cost.state: held). When it finishes, the hold is
replaced by the charge for the measured usage (cost.state: settled), and anything left is released.
A run that fails on Spiral’s side or the provider’s is not charged: the hold goes back to your balance.
Prices in your own unit
If you resell Spiral to your own users in a unit of your own (credits, points) with your own markup, Spiral can state every price in that unit for you, so you never convert or reword its USD amounts. Owners and admins turn it on in the console under Settings › Customer pricing, where a preview shows real tools priced both ways before you save. It is off by default: the API then answers in Spiral’s USD prices only. It has five values:- Markup, from 1 to 100 with up to 4 decimal places: how much above Spiral’s price you charge.
1.3means your price is 30% above Spiral’s. - Unit name, 1 to 32 characters: the word your users see after each amount, such as
credits, exactly as written. - Units per dollar: how many of your units one dollar of Spiral’s price is worth, before the markup, with no more decimal places than you choose below. One dollar can be worth at most 10^12 minor units, so the largest value depends on the decimal places: 1,000,000 at 6, 10,000,000,000 at 2, 10^12 at 0.
- Decimal places, 0 to 12 (6 by default): how precisely an amount is stated. A run’s amount rounds up to the last place.
- Put a space between the amount and the unit, on by default (“0.5 credits”). Turn it off for a unit written
against the number, such as
M credits(“0.5M credits”).
customer_price beside it: the estimate’s customer_price and the run’s
cost.customer_price, with estimated and charged. minor_units is
ceil(USD amount × markup × minor units per dollar), so a nonzero price is never 0, and amount is the same value in your
unit as an exact decimal. A minor_units too large for a JSON number to state exactly (above 2^53 − 1) is null;
amount is always exact. With a markup of 1.3, 1 credit per dollar and 6 decimal places, a hold of $0.78 is:
customer_price is what you charge
your users. Without the setting, customer_price is null.
Inspect a model (MCP inspect) then also answers customer_price_description: the
same price description with every amount in your unit with your markup, so you can show it to your users as it is. Each
amount is exact when it ends within 12 decimal places, otherwise rounded up to 4 significant digits. Without the
setting, it is null.
customer_price is unchanged.
Keys for your own users
Your own billing keeps reading Spiral’s USD cost, but the agents and apps your users reach should see only your price. Set those keys to the customer price view: an owner or admin opens API keys in the console, chooses Prices shown in the key’s menu and picks Customer. A key shows Customer prices next to its name while it is set. Turn on customer pricing first (Settings › Customer pricing): without it the choice is not available. Standard, every key’s default, sets it back. A change applies from the key’s next request. Every answer to such a key, over the API and MCP, states no USD amount: the estimate’sestimate and the run’s cost are null, and the run answers customer_cost instead:
{state, unit, estimated, charged}, the run’s cost.customer_price with the cost’s state. A tool’s
price_description, worded in USD, is null; its customer_price_description (above) states the price in your unit. A
refusal for your balance or a key’s spend cap states no amount either, and a provider’s own bill inside a run’s output
(for example usage.cost in a chat completion) is removed. A large output stored as a file is given from a copy
without that bill. Where Spiral holds no such copy, the output is withheld instead: it is listed with
error.code: OUTPUT_UNAVAILABLE and no link, even though the run completed and was charged. Read it with a standard
key. Such a key cannot read the account balance
(GET /v1/balance and get_balance answer 403 PERMISSION_DENIED with reason: price_view): read it with your own
key. Nor can it call the LLM APIs, whose answers pass the model’s usage through with its cost:
they answer the same 403. A run’s webhook keeps the view of the key that started it. Every other key answers as described above. The view
changes only what is shown: Spiral charges your balance the same USD amount.