What a run cost you locally — a spend estimate at rates you configure, priced from the run's own durable counters.

Cost in Kortecx is a local spend estimate at rates you configure, with a ceiling — not a bill.

Nobody charges you for running the agentic runtime on your own machine. What the runtime gives you is a number you can act on: how much work a run actually did, priced at rates you set.

What gets counted

Two durable counters, both recorded as the run happened:

turns — how many times a model was asked to think.
tool calls — how many times the run reached out to do something.

The estimate is one line of arithmetic:

estimate = turns × per-turn rate  +  tool calls × per-tool-call rate

Rates are integers in micro-USD (a millionth of a dollar), so the sum is exact — there is no floating-point drift in a number you might enforce a limit against. The arithmetic saturates rather than wrapping, so a runaway count can never overflow into a small, harmless-looking figure.

No token pricing here

The estimate prices turns and tool calls — not tokens. There is no input-token figure in the local runtime, so none is shown. Per-token billing — invoices, credits, an itemised statement — belongs to Kortecx Cloud, and is never invented locally.

Read a run's cost

You need the run's instance id, which kx runs list prints as the first column of each row, in hexadecimal. That is the exact form kx cost expects.

List your runs and copy an instance id.

kx runs list

Ask for that run's cost.

kx cost <instance-id>

A run with 12 turns and 5 tool calls, at the default rates, reads:

turns=12  tool_calls=5  estimated=$0.014500  (rates: 1000/500 µ$ per turn/call)

That line is illustrative — the shape of the output, not a measurement we took. The arithmetic is the fold above at the default rates: 12 × 1000 + 5 × 500 = 14500 micro-USD.

The rates are printed alongside the figure on purpose. A dollar estimate means nothing without the price you set, so the readout always carries its own provenance.

For a machine, add --json.

kx cost <instance-id> --json

{
  "instance_id": "…",
  "turns": 12,
  "tool_calls": 5,
  "estimated_micro_usd": 14500,
  "ceiling_micro_usd": 0,
  "per_turn_micro_usd": 1000,
  "per_tool_call_micro_usd": 500,
  "over_ceiling": false
}

The instance id can also be passed as --instance <instance-id> instead of positionally.

Set your own rates

The defaults are notional — 1000 µ$ per turn and 500 µ$ per tool call. They exist so the guardrail prices something out of the box. Replace them with numbers that mean something to you by setting two environment variables on the process that serves the runtime:

KX_PRICING_PER_TURN_MICRO_USD=2500 KX_PRICING_PER_TOOL_CALL_MICRO_USD=100 kx serve --dev-allow-local

Both are read as whole micro-USD integers. A missing or malformed value falls back to the existing rate — a typo never silently zeroes your price book. The rates are resolved from the environment when the serve process starts, so set them on that command, not on the kx cost call.

The ceiling

A run carries a cost ceiling on its warrant, the permission slip that says what the run is allowed to do. The ceiling is a whole number of micro-USD and defaults to 0, which means unset — nothing is enforced. When a run's warrant carries a positive ceiling, the runtime prices the run's committed turns and tool calls before each batch of tool work; if the estimate has passed the ceiling, the chain is dead-lettered — stopped and set aside — instead of dispatching more work.

You cannot set a ceiling yet

The enforcement path is in the runtime, but there is no way to set a positive ceiling from the command line, the SDKs or an app manifest today. The cost_ceiling axis is deliberately not carried on the wire, and the manifest field of that name is marked reserved, so every run submitted through the gateway gets the default 0 — off. For the same reason kx cost always reports ceiling_micro_usd: 0 and over_ceiling: false. Treat the ceiling as an enforcement axis that is wired but not yet reachable. Until it is, kx cost is a readout you check, not a limit that stops anything.

The design rule for that axis is already fixed: a ceiling can only ever be narrowed. When one agent delegates to another agent inside the same app, the child warrant takes the lower of the two ceilings — spend authority never grows on the way down.

The token side of the picture

The cost estimate is deliberately coarse. If you want to see where the work went by model, read the telemetry rollup instead:

kx telemetry summary --json

It sums output tokens and wall-clock per model, across every run, and takes --instance <instance-id> to scope to one. Each row carries model_id, count, total_output_tokens and total_wall_clock_ms. There is no cost column and no input-token column — neither is available locally, so neither is fabricated. If your serve predates the telemetry sidecar, the command says so rather than inventing an empty answer.

From the SDKs

kx cost <instance-id> --json

cost = client.cost.get_run_cost(instance_id)
print(cost.turns, cost.tool_calls, cost.estimated_micro_usd)

const cost = await client.cost.getRunCost(instanceId);
console.log(cost.turns, cost.toolCalls, cost.estimatedMicroUsd);

The command line and both SDKs read the same call, so the figure is the same wherever you ask for it.

Observability

Telemetry, the alerts inbox, and the opt-in Prometheus endpoint.

Approvals

The other brake: a human decision before a run acts.

Cost