How Veqen works
The price book, tags, the local and cloud ledgers, and what happens to a call from your code to the dashboard.
The path of one call
- 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.
- 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.
- 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.
- 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/eventsevery two seconds. - 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 or download prices.json. See 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, 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.
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.