# How Veqen works

## The path of one call

1. Your code calls a wrapped client. The SDK checks local and cloud **budgets** in memory; if one is exhausted in block mode, it raises before the request leaves your process.
2. The provider responds. The SDK reads the **usage** the provider reported: input tokens, output tokens (reasoning included), cache reads and writes, audio tokens, or the images, seconds or characters a media model billed.
3. The SDK **prices** the call with the bundled price book and the call's options (batch, service tier, data residency), then attaches the current **tags**.
4. The event goes to a local ledger file (if you set one) and, with an API key, into an in-memory queue that a background thread sends to `/v1/events` every two seconds.
5. The cloud ledger **prices it again** with its own copy of the price book (so every SDK version is priced the same way), stores it once (a retry with the same id and timestamp is a duplicate), adds it to daily rollups, and counts it against your plan.

Nothing in that path blocks your request. If Veqen is unreachable, events wait in the queue (up to 50,000) and are retried.

## The price book

Prices come from each provider's published rates, built from LiteLLM's MIT-licensed price file plus Veqen's verified rules:

| Rule | Example |
|---|---|
| Cache reads | Cached input billed at a tenth of the input rate on most models |
| Cache writes | Anthropic's 5-minute and 1-hour cache writes, priced separately |
| Batch | Batch API rates, usually half price |
| Service tiers | Priority and flex, where the provider publishes rates for them (OpenAI, Google) |
| Long context | Higher rates once a prompt passes 200K tokens |
| Data residency | US-only Anthropic processing at 1.1× |
| Per-unit models | Images by size and quality, video by second and resolution, speech by character, transcription by second |

Every price carries the price book's version (a date). The book is checked against its sources every day; changes reach the cloud ledger with its next deploy and the SDKs with their next release. Browse it at [/models](/models) or download [prices.json](/prices.json). See [Price book](/docs/price-book) for the rules in detail.

Models the price book doesn't know (fine-tunes, private deployments) are still recorded, with a null cost. Give them a [custom price](/docs/custom-prices), or pass `cost_usd` to `record()`.

## Tags

Five tags have their own columns: `customer`, `feature`, `user`, `project` and `environment`. Anything else goes into free-form tags. Set them once around the code that makes calls; they follow async code automatically. See [Tags](/docs/tags).

## Local and cloud

| | Without a key | With a key |
|---|---|---|
| Pricing | ✓ | ✓, re-priced by the cloud ledger |
| Local ledger file and `veqen report` | ✓ | ✓ |
| Local budgets | ✓ (per process) | ✓ |
| Shared budgets across servers | – | ✓ |
| Dashboard, API, MCP | – | ✓ |
| Reconciliation, margin, credits, close | – | ✓ |

## What Veqen doesn't do

Veqen isn't a proxy or a gateway: it never sits between you and the provider, so it can't add latency or become an outage. It isn't a tracing or evaluation tool either; it keeps the books.