> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valarhq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cost per request

> Read what each request cost directly from its response

Every response Valar returns reports the tokens it used. With per-request cost reporting on, it also reports what those tokens cost you: `usage.cost`, in US dollars, priced on the rates your organization is billed, so you can attribute spend to a request, a user or a feature the moment the answer arrives, without waiting for the [Usage API](https://docs.valarhq.ai/usage.md).

The field follows the `usage.cost` convention OpenAI-compatible gateways already use, a number in US dollars, so tooling that reads `usage.cost` reads a Valar response without changes.

> [!NOTE]
>
> Per-request cost reporting is enabled per organization. If your responses do not carry `usage.cost` yet, ask \[[support@valarhq.ai](mailto:support@valarhq.ai)]\(mailto:[support@valarhq.ai](mailto:support@valarhq.ai)) to turn it on. Nothing else in the response changes.

## What you get

One field joins the usage block you already receive. The token fields keep each API's own convention.

```json theme={null} theme={"system"}
"usage": {
  "prompt_tokens": 1000,
  "completion_tokens": 100,
  "total_tokens": 1100,
  "prompt_tokens_details": { "cached_tokens": 400, "cache_write_tokens": 50 },
  "cost": 0.002325
}
```

| Field | Meaning |
| - | - |
| `cost` | The reported cost of the request, in USD, to six decimal places. See [How it relates to your bill](#how-it-relates-to-your-bill) for rounding and rate-change differences. |

The price is computed with the same arithmetic and the same rate card as the spend the [Usage API](https://docs.valarhq.ai/usage-endpoints.md) reports: your negotiated rates where you have them, otherwise the [published rates](https://docs.valarhq.ai/pricing.md), with cache reads, cache writes and the long-context band applied exactly as they are billed. Summing `cost` lets you track spend per request; rounding and rate changes can make the total differ from the Usage API.

## Where it appears

* **Non-streaming responses** carry it in `usage`.
* **Streaming responses** carry it in the final frame that reports usage: `response.completed` on the Responses API, the trailing `usage` chunk on Chat Completions (send `stream_options.include_usage: true`), and `message_delta` on the Messages API.
* **`GET /v1/responses/{id}`** and idempotent replays carry it too, priced on the response's own tier, so a Standard or Flex request you poll for later reports its window's price.

A request that did not finish (`failed` or `cancelled`) is never billed and carries no `cost`. An `incomplete` response that hit `max_output_tokens` is billed and priced like any other. A request served on your own provider key reports `cost: 0`.

### ValarCode

Requests sent with ValarCode credentials (a coding key, or an SSO sign-in) carry `cost` the same way, whether they come from Claude Code, Cursor, Codex or your own calls to the endpoints above. Two exceptions answer without the field: a request reviewed by an advisor model (such as `valar/fusion`), and a streamed Chat Completions request that did not ask for usage.

## Reading it from an SDK

OpenAI and Anthropic SDKs keep fields they do not model, so the value is reachable without any change to your client:

```python theme={null} theme={"system"}
from openai import OpenAI

client = OpenAI(base_url="https://api.valarhq.ai/v1", api_key=VALAR_API_KEY)
resp = client.responses.create(model="zai-org/GLM-5.3", input="Summarize this ticket")
print(resp.usage.model_extra["cost"], "USD")
```

```python theme={null} theme={"system"}
from anthropic import Anthropic

client = Anthropic(base_url="https://api.valarhq.ai", api_key=VALAR_API_KEY)
msg = client.messages.create(model="zai-org/GLM-5.3", max_tokens=256,
                             messages=[{"role": "user", "content": "Summarize this ticket"}])
print(msg.usage.model_extra["cost"], "USD")
```

```bash theme={null} theme={"system"}
curl -s https://api.valarhq.ai/v1/chat/completions \
  -H "Authorization: Bearer $VALAR_API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"zai-org/GLM-5.3","messages":[{"role":"user","content":"hi"}]}' \
  | jq '.usage.cost'
```

## How it relates to your bill

Two things can make a later read differ from the live one: a rate change between the request and a `GET` of its response (the response is priced at the rate in force when it is read), and rounding, which the Usage API applies in cents and `cost` in millionths of a dollar. The rates themselves are in [`GET /v1/models`](https://docs.valarhq.ai/api-reference/models-api/list-supported-models), resolved for your organization.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.