# 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 and the model that served it. 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. Both named-model and [Cortex](https://docs.katara.com/concepts/cortex.txt) replies include `katara.served.model`, the concrete model id. Provider replies also name the bundle and provider in that block.

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",
  "served": { "model": "katara/deepseek-chat@1" }
}
```

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 0.025 USDC minimum included.

In a stream the `katara` object arrives as a final chunk with an empty `choices` array, after usage and before `[DONE]`. Chat labels each reply with the selected model's friendly name, or Katara Cortex when Cortex was selected. The detail line shows the model that served it.

## What counts as output

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.

## 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.