{"id":13020,"date":"2026-09-13T07:35:00","date_gmt":"2026-09-13T05:35:00","guid":{"rendered":"https:\/\/www.lukaswojcik.com\/blog\/?p=13020"},"modified":"2026-10-26T12:44:08","modified_gmt":"2026-10-26T11:44:08","slug":"tutorial-measuring-token-consumption-per-request-and-enforcing-a-monthly-budget","status":"publish","type":"post","link":"https:\/\/www.lukaswojcik.com\/blog\/en\/cloud-ai\/tutorials-en-cloud-ai\/tutorial-measuring-token-consumption-per-request-and-enforcing-a-monthly-budget\/","title":{"rendered":"Tutorial: Measuring Token Consumption per Request and Enforcing a Monthly Budget"},"content":{"rendered":"

A useful API budget connects three records: a reservation before a request, measured usage after the response and a later reconciliation with provider charges. A token total alone is insufficient. Provider, model, service tier, cache class and additional tools can change the price.<\/p>\n

1. The provider\u2019s usage schema<\/h2>\n

In Anthropic Messages, input_tokens<\/code> describes uncached input, while cache creation and cache reads are separate input categories. Cache creation can be split by lifetime. In OpenAI Responses, input_tokens<\/code> is the input total; cached tokens and supported cache-write categories are included within it. Adding them to that total would count input twice. These are different accounting structures, not merely different names.<\/p>\n

The following invented normalized record uses four non-overlapping classes. The rates are arithmetic examples in USD per million tokens, not a current quotation for a named model. A real adapter must handle the selected endpoint and all applicable cache lifetimes.<\/p>\n

from decimal import Decimal, ROUND_CEILING\n\n# Fictional normalized classes and example USD rates per million.\ncounts = {"input": 12400, "write_5m": 8200, "read": 96000, "output": 1850}\nrates = {k: Decimal(v) for k, v in {\n    "input": "3.00", "write_5m": "3.75", "read": "0.30", "output": "15.00"\n}.items()}\ncost_usd = sum(Decimal(counts[k]) * rates[k] for k in counts) \/ Decimal(1_000_000)\nactual_u = int((cost_usd * 1_000_000).to_integral_value(rounding=ROUND_CEILING))\nprint(cost_usd, actual_u)  # 0.1245, 124500\n<\/code><\/pre>\n
The exact components are USD 0.0372, 0.03075, 0.0288 and 0.02775, totalling USD 0.1245. Rounding every displayed component first can change the apparent sum. Decimal arithmetic retains the calculation; the reservation ledger below uses integer micro-USD, where USD 1 equals 1,000,000 units. Rounding upward to that unit is a local budgeting policy, not the provider\u2019s invoice rule.<\/p>\n
\"Four
Four stages of API budget control<\/figcaption><\/figure>\n
2. Counting before sending and recording after completion<\/h2>\n
Anthropic\u2019s counting endpoint is free within its rate limits and provides an estimate without applying caching logic. It does not accept every input supported by Messages: the current documentation excludes most server tools, the MCP connector and URL\/file-sourced image or document blocks. The model and complete supported request structure matter. A plain-text tokenizer is not a universal estimator for tools, images or message framing.<\/p>\n
Streaming usage does not universally appear only in the last event. Anthropic supplies initial usage in message_start<\/code> and cumulative updates in message_delta<\/code>; adding every cumulative value would overcount. For example, successive totals of 10 and 20 mean 20 tokens so far, not 30. A supported SDK\u2019s completed-message helper simplifies collection. Interrupted streams and failed connections can leave incomplete usage. Missing data must remain unknown, not become zero.<\/p>\n
A durable audit record should link logical operation, unique attempt ID, provider request\/response ID when available, timestamps, feature, provider\/model, pricing snapshot, reservation and raw usage. Prompts and API keys are unnecessary for this ledger. A retry is a distinct attempt whose possible charge needs its own reservation. A timeout neither proves a charge nor proves that processing stopped; a response header may never have reached the client.<\/p>\n
3. A single transaction for the full reservation<\/h2>\n
The upper bound must cover input, the maximum applicable output, possible cache writes and bounded tool or loop costs. Maximum output alone is not enough. Unknown pricing, unbounded tool loops or a failed ledger write must prevent dispatch. Cache hits should not be assumed when computing the bound.<\/p>\n
This executable ledger.py<\/code> demonstrates admission control for one application, one currency and one UTC calendar-month policy. All callers must use the same local SQLite database. It is not a multi-host database or a complete billing integration. The amount validator caps each value at one million USD in micro-units.<\/p>\n
Before the first reservation, initialise(database_path)<\/code> creates the tables. Output usage can include non-visible reasoning or formatting tokens; visible answer length is not the output meter.<\/p>\n
import sqlite3\nfrom datetime import datetime, timezone\n\nclass BudgetExceeded(Exception):\n    pass\n\ndef units(value):\n    if type(value) is not int or not 0 <= value <= 10**12:\n        raise ValueError("Expected non-negative integer micro-USD, at most 10^12")\n    return value\n\ndef connect(path):\n    db = sqlite3.connect(path, timeout=10, isolation_level=None)\n    db.execute("PRAGMA foreign_keys=ON")\n    return db\n\ndef initialise(path):\n    db = connect(path)\n    try:\n        db.executescript("""\n        CREATE TABLE IF NOT EXISTS budgets(\n          month TEXT PRIMARY KEY, limit_u INTEGER NOT NULL,\n          breached INTEGER NOT NULL DEFAULT 0);\n        CREATE TABLE IF NOT EXISTS calls(\n          attempt_id TEXT PRIMARY KEY,\n          month TEXT NOT NULL REFERENCES budgets(month),\n          reserved_u INTEGER NOT NULL, actual_u INTEGER,\n          state TEXT NOT NULL CHECK(state IN ('pending','settled')));\n        """)\n    finally:\n        db.close()\n\ndef reserve(path, attempt_id, upper_u, limit_u, now=None):\n    upper_u, limit_u = units(upper_u), units(limit_u)\n    if not isinstance(attempt_id, str) or not attempt_id:\n        raise ValueError("Stable, nonempty attempt ID required")\n    now = datetime.now(timezone.utc) if now is None else now\n    if now.tzinfo is None or now.utcoffset() is None:\n        raise ValueError("Timezone-aware timestamp required")\n    month = now.astimezone(timezone.utc).strftime("%Y-%m")\n    db = connect(path)\n    try:\n        db.execute("BEGIN IMMEDIATE")\n        if db.execute("SELECT 1 FROM calls WHERE attempt_id=?",\n                      (attempt_id,)).fetchone():\n            db.commit()\n            return False  # No second permission to send.\n        db.execute("INSERT OR IGNORE INTO budgets(month,limit_u) VALUES (?,?)",\n                   (month, limit_u))\n        stored_limit, breached = db.execute(\n            "SELECT limit_u,breached FROM budgets WHERE month=?", (month,)\n        ).fetchone()\n        if stored_limit != limit_u:\n            raise ValueError("Conflicting limit for this month")\n        used = db.execute(\n            "SELECT COALESCE(SUM(COALESCE(actual_u,reserved_u)),0) "\n            "FROM calls WHERE month=?", (month,)\n        ).fetchone()[0]\n        if breached or used + upper_u > limit_u:\n            raise BudgetExceeded(month)\n        db.execute("INSERT INTO calls VALUES (?,?,?,?,?)",\n                   (attempt_id, month, upper_u, None, "pending"))\n        db.commit()\n        return True\n    except BaseException:\n        db.rollback()\n        raise\n    finally:\n        db.close()\n\ndef settle(path, attempt_id, actual_u):\n    actual_u = units(actual_u)\n    db = connect(path)\n    try:\n        db.execute("BEGIN IMMEDIATE")\n        row = db.execute(\n            "SELECT month,reserved_u,actual_u,state FROM calls WHERE attempt_id=?",\n            (attempt_id,)\n        ).fetchone()\n        if row is None:\n            raise ValueError("Unknown attempt")\n        month, reserved, old_actual, state = row\n        if state == "settled":\n            if old_actual != actual_u:\n                raise ValueError("Conflicting settlement")\n            db.commit()\n            return\n        db.execute("UPDATE calls SET actual_u=?,state='settled' WHERE attempt_id=?",\n                   (actual_u, attempt_id))\n        if actual_u > reserved:\n            db.execute("UPDATE budgets SET breached=1 WHERE month=?", (month,))\n        db.commit()\n    except BaseException:\n        db.rollback()\n        raise\n    finally:\n        db.close()\n<\/code><\/pre>\n
BEGIN IMMEDIATE<\/code> acquires the write transaction before reading the total. This prevents two concurrent callers from reserving the same remaining budget. The reservation is committed before the network request; the transaction is not held while waiting for the API. Only a true return from reserve()<\/code> permits dispatch. False means that the attempt already exists, not permission to send it again. A lock or database error must stop the call.<\/p>\n
PSEUDOCODE\nvalidate provider, model, pricing snapshot and complete cost bound\npersist a unique attempt ID and audit context\nif reserve(database, attempt_id, upper_bound_u, monthly_limit_u) is True:\n    send exactly one provider attempt outside the database transaction\n    on complete usage:\n        persist the original usage and provider identifiers\n        calculate cost with the recorded pricing snapshot\n        settle(database, attempt_id, actual_cost_u)\n    on unknown outcome or unknown cost:\n        keep the reservation pending and investigate\n<\/code><\/pre>\n
The stored limit is fixed for that month. A later breach flag does not cancel requests already admitted.<\/p>\n
The flow is pseudocode for the provider adapter: a reviewed pricing snapshot and a complete bound are prerequisites. The actual code above performs no API call. It records a settlement once, accepts an identical repeated settlement and rejects conflicting amounts. If the actual cost exceeds the reservation, it records that fact and blocks further admissions for that month. It cannot undo spend already incurred.<\/p>\n
4. Visible records of uncertain attempts<\/h2>\n
A crash after reservation but before dispatch can leave unused funds reserved. A timeout after dispatch can leave real spend unresolved. Automatically expiring both cases would reopen the budget without evidence. Recovery needs the audit record and provider information; only confirmed no-charge attempts should settle at zero.<\/p>\n
The month is assigned when the application reserves the attempt in UTC. Settlement remains attached to that month, even if it arrives later. This is an internal policy, not a statement about invoice timing. Submission, execution, settlement and provider billing periods should remain separate for asynchronous batches and month-boundary reconciliation.<\/p>\n
\n
Questions and answers<\/h2>\n
Does this guarantee the provider invoice stays below the budget?<\/h3>\n
No. The bound, pricing adapter and routing of every charged operation must be correct. Other API keys, omitted tool charges, contract terms, taxes or later adjustments can sit outside the local ledger. Provider-side limits can add protection where available, but their documented scope matters.<\/p>\n
Can reconciliation always match each request?<\/h3>\n
No. Anthropic\u2019s Usage and Cost APIs provide aggregated time buckets and grouping dimensions; a request-by-request export must not be assumed. Cost reporting also has documented coverage limits. Matching periods, currency and scope is necessary before interpreting a difference.<\/p>\n
What did the example tests establish?<\/h3>\n
Eight parallel reservation attempts admitted only two amounts of 40 under a limit of 100. Further isolated tests covered duplicate settlements, uncertain pending attempts, conflicting limits, invalid amounts and UTC month boundaries. No paid API request or real invoice was tested.<\/p>\n<\/div>\n
Sources<\/h2>\n