# Usage and cost

> Where the settled price shows up, and how to reconcile your own accounting with it.

Section: Developers. Web page: https://docs.katara.com/developers/usage/

Every successful reply reports its charge. Credits are the account balance that pays for requests when a key or the chat app is set to credits: the signup credit every new account starts with, and credits bought by card. Credit charges debit that balance; USDC charges settle on chain.

## On the response

```json
"usage":  { "prompt_tokens": 18, "completion_tokens": 52, "total_tokens": 70 },
"katara": { "cost_usdc": "0.000018", "provider": "0xfFe5…38DC" }
```

`cost_usdc` is a decimal string in USDC. `provider` is the address of the provider that served you, or `managed` when a vendor answered. The reply does not name the model behind [Cortex](https://docs.katara.com/concepts/cortex.txt); the signed receipt does.

For a Credits request, the charge uses the existing `cost_usd` field with `billing_method: "credits"`. Despite the legacy field name, display the amount as Credits without a dollar sign:

```json
"katara": {
  "billing_method": "credits",
  "cost_usd": "0.000018"
}
```

A request paid with [x402](https://docs.katara.com/developers/x402.txt) also carries `katara.payment`: the scheme it was paid with, the network, the token and `amount`, the charge in the token's base units, which is the `amount` in its `PAYMENT-RESPONSE` header. Its `cost_usdc` is that charge, the model's minimum included: 0.025 USDC for `katara/cortex`, 0.05 for `katara/cortex-genius` and 0.01 for `katara/cortex-smart`.

In a stream the `katara` object arrives as a final chunk with an empty `choices` array, after usage and before `[DONE]`.

A request that searched the web carries `katara.web_search`, the number of charged searches and their cost, and its `cost_usdc` or `cost_usd` is the total of every model call and every search ([Web search](https://docs.katara.com/developers/tools.txt#web-search)). `usage` then sums the tokens of every model call the request made. A request that searched and ended without an answer is charged nothing for its searches or the model calls after them; only a first call that Katara Community served stays charged.

## What counts as output

On Katara Community, output tokens are what you received, measured with the model's own tokenizer: the assistant text, and for each tool call its name and its argument document. A model's private syntax around a call, anything Katara refused, and the runtime's own token report are not billed. Both the provider and Katara compute the count independently from the same delivered content, and a reply only settles when the two agree exactly. Input tokens come from the runtime's count of the rendered prompt, bounded by the size of your request.

A vendor model's reply is billed on the vendor's own counts, at the price Katara lists for it. Its reasoning counts as output whether or not it is shown. When Katara ends a reply at one of your stop sequences, or at a `max_tokens` below the model's own floor, the tokens the vendor wrote past that point are still billed.

## Retries

Every request is charged at most once. A USDC reply settles against its own signed receipt, and a receipt can settle once. A Credits request finalizes one reservation for its delivered usage. A failed attempt on one provider is retried on another inside the same request and never charged. If you retry a request yourself after a timeout, that is a new request. The chat apps' own service honours an `Idempotency-Key` header; the marketplace API does not read it.

## Bounding cost

`max_tokens` bounds the output and so the maximum charge. The admission check uses it: a request whose maximum exceeds your spendable balance is refused before any work. Keep `max_tokens` honest for what you need and long prompts will fit in a smaller balance.

## Reconciling

The portal's usage page lists every request with its id, model, tokens, and cost. Match rows to your logs by `x-katara-request-id`. USDC settlements are visible on chain under your wallet address. Credits purchases, reservations and debits are available in the billing statements.