# Usage & billing

> The usage object and usage.cost, how cost is computed, the generation ID header, checking your key, and what is billed.

Source: https://kiln.bricksum.com/docs/en/usage-billing

You pay from prepaid credits in USD. The usage object in a response carries the token counts and the cost in USD, which the gateway adds. This page explains that object, how the cost is computed, the request ID header, and what is and is not billed.

## The usage object

Non-streaming responses carry usage in the body in the OpenAI shape, plus one field that the gateway adds:

- prompt_tokens, completion_tokens and total_tokens.
- prompt_tokens_details.cached_tokens, when the model server served part of the prompt from its prefix cache. These tokens are billed at the lower cached-input price.
- completion_tokens_details.reasoning_tokens, when the model reports reasoning. These tokens are part of completion_tokens and are billed as output.
- cost: the amount in USD charged to your credits for this request. It is added by the gateway, not by the model.

In a stream the same object arrives in the final chunk when you set stream_options.include_usage; see [Streaming](https://kiln.bricksum.com/docs/en/streaming).

**200 OK**
```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "qwen3-32b",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello! How can I help?" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21,
    "cost": 0.000001155
  }
}
```

The token counts and cost in these examples are illustrative figures measured on gpt-oss-120b, not qwen3-32b's.

## How cost is computed

Cost is the sum of three terms, using the model's per-token prices at the time of the request. Cached prompt tokens are a subset of prompt_tokens and are charged at the cached-input price instead of the input price.

**USD**
```text
cost = (prompt_tokens - cached_tokens) x input price
     + cached_tokens                  x cached-input price
     + completion_tokens              x output price
```

The prices per 1M tokens for every model are on the [model catalog](https://kiln.bricksum.com/models); the catalog API returns them as price_input_per_m, price_cached_input_per_m and price_output_per_m. Prices are in USD, VAT not included.

## Request ID header

Every metered response carries the `X-Neocloud-Generation-Id` header: the ID of the usage event for that request. Store it with your request logs and include it when you contact support about a charge or an error.

## Check your key

GET /v1/key, authenticated with the key itself, returns that key's project, status, spend limit, expiry and spend so far. A teammate can use it to check a key without console access. The plaintext key is never returned. Invalid, suspended and expired keys all get 401.

**curl**
```bash
curl https://api.bricksum.com/v1/key \
  -H "Authorization: Bearer sk-bk-..."
```

**200 OK**
```json
{
  "id": "key_...",
  "org_id": "org_...",
  "project_id": "proj_...",
  "name": "prod-backend",
  "prefix": "sk-bk-",
  "last4": "a1b2",
  "status": "active",
  "spend_limit_usd": 50,
  "expires_at": null,
  "usage_usd": 12.34,
  "last_used_at": "2026-09-11T07:00:00Z",
  "created_at": "2026-08-01T00:00:00Z"
}
```

## What you are billed for

- One usage event per request that reached the model server, from the usage counts the server reported.
- Requests rejected by the gateway before reaching the model are not billed. The status codes and their causes are listed on [Errors](https://kiln.bricksum.com/docs/en/errors).
- If the model server returns an error or fails mid-stream, the event records 0 tokens and nothing is charged.
- If your client disconnects mid-stream, the gateway drains the stream to record usage; the tokens generated are charged.

## When requests are refused

The gateway returns `402 Payment Required` before calling the model in three cases: your organization's credit balance is zero or below, the organization has reached its monthly budget, or the key has reached its spend limit. Requests refused this way are not billed. Balance, ledger and expiry are on the [credits page](https://kiln.bricksum.com/app/credits). Budgets, key limits and credit expiry are explained on the Organizations & budgets page.