LLM auto-capture

nozle.wrap_http_client() makes the HTTP client your LLM SDK uses record the token usage of every successful response. It works with any client built on httpx or its fork httpx2, sync or async, including the OpenAI and Anthropic SDKs. Requests and responses pass through unchanged, and prompts and completions are never sent to Nozle. wrap_http_client(), capture_http_client(), capture_async_http_client() and record_usage() require nozle-sdk 0.13.0. The client wrappers are available in earlier versions. Usage is recognised by the shape of the response, not by provider name: an OpenAI-style usage (OpenAI chat completions, the Responses API and any OpenAI-compatible API such as OpenRouter, Groq, Azure OpenAI or vLLM), an Anthropic usage, or Gemini usageMetadata. JSON responses and streams are both read, including a stream your client closes at [DONE].

Capture records usage events; they bill only when a metered Feature has the same event code. See Set up AI token billing for the Feature, charge and cost model to create first.

Capture any client

pip install "nozle-sdk[httpx]"

import openai
import anthropic
from nozle import Nozle

nozle = Nozle()  # reads NOZLE_SECRET_KEY

client = openai.OpenAI(
    http_client=nozle.wrap_http_client(openai.DefaultHttpxClient(), customer_id="workspace_123"),
)
claude = anthropic.Anthropic(
    http_client=nozle.wrap_http_client(anthropic.DefaultHttpxClient(), customer_id="workspace_123"),
)

Pass the SDK’s own DefaultHttpxClient() (or DefaultAsyncHttpxClient() for AsyncOpenAI and AsyncAnthropic): each SDK expects the HTTP package it was built with, and wrap_http_client keeps that package. nozle.capture_http_client(customer_id=...) builds a new httpx.Client instead (module="httpx2" for httpx2), and capture_async_http_client an async one.

One client for every customer

customer_id can be a function, called with each httpx request, or a request can name its customer with the X-Nozle-Customer-Id header. The header wins and is removed before the request reaches the provider; so is X-Nozle-Feature, which sets the feature property. A request without a customer passes through and nothing is recorded.

client.chat.completions.create(
    model="example-chat-model",
    messages=messages,
    extra_headers={"X-Nozle-Customer-Id": workspace.id},
)

Argument	Description
`customer_id`	Customer to bill: a string, or a function of the request.
`feature_code`	Feature code of the usage event. Default `llm_tokens`.
`feature`	Stored as the `feature` property.
`cost_meter_code`	Also send one Cost Event per token category to this Cost Event Meter.
`include_stream_usage`	Default `True`: chat completion streams are sent with `stream_options.include_usage`. Set `False` for a server that rejects the field.
`on_error`	Called with a recording failure, and once per event code with an error whose `code` is `feature_not_found` when no Feature has that code. Without it, a `NozleTrackingWarning` is emitted. The provider response is never affected.

Recording runs in a background thread (with AsyncNozle, a task on the event loop) after the response has been read.

Usage you read yourself

nozle.record_usage(
    "workspace_123",
    model=response.model,
    request_id=response.id,       # makes the event id stable
    input_tokens=1200,            # all input, including cached input
    cached_input_tokens=300,
    output_tokens=400,            # all output, including reasoning
    provider="openai",
)

record_usage raises if the usage could not be recorded.

Client wrappers

wrap_openai and wrap_anthropic record the usage of chat.completions.create (OpenAI) and messages.create (Anthropic) instead, for synchronous and asynchronous calls and streams. They are kept for existing integrations; wrap_http_client also covers the Responses API, Gemini and OpenAI-compatible providers.

From 0.13.1, wrap_openai and wrap_anthropic return a view of the client and never change the client you pass in. Always call the returned client: calls on the original client record nothing. Code that ignored the return value and kept calling the original client recorded usage in 0.13.0 and earlier, and records nothing from 0.13.1.

Each view records usage once per call, for its own customer_id, for sync and async clients and streams, so a server can keep one provider client and wrap it per request: wrap_openai(shared_openai, nozle, customer_id=request.team_id). Every other attribute is read from the original client, and isinstance(view, OpenAI) / isinstance(view, Anthropic) still holds. Views over the same client are independent, including concurrent async streams, and wrapping an already wrapped client wraps its original, so wrappers never stack. Before 0.13.1, each wrap replaced create on the shared client, so one call recorded an event for every customer the client had been wrapped for.

OpenAI

pip install "nozle-sdk[openai]"

import os
from openai import OpenAI
from nozle import wrap_openai


nozle = Nozle(
    api_key=os.environ["NOZLE_SECRET_KEY"],
    base_url="https://api.nozle.app/engine",
    events_url="https://api.nozle.app/core",
)

openai = wrap_openai(
    OpenAI(),
    nozle,
    customer_id="workspace_123",
    metric_code="llm_tokens",
    cost_meter_code="ai_tokens",
    feature="assistant_reply",
)

response = openai.chat.completions.create(
    model="example-chat-model",
    messages=[{"role": "user", "content": "Hello"}],
)

OpenAI streaming

The wrapper sets stream_options.include_usage to true so the final stream chunk contains token counts. Only include_usage is overwritten; other stream_options keys you pass are kept.

stream = openai.chat.completions.create(
    model="example-chat-model",
    messages=[{"role": "user", "content": "Explain vector search"}],
    stream=True,
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Anthropic

pip install "nozle-sdk[anthropic]"

from anthropic import Anthropic
from nozle import wrap_anthropic


anthropic = wrap_anthropic(
    Anthropic(),
    nozle,
    customer_id="workspace_123",
    metric_code="llm_tokens",
    cost_meter_code="ai_tokens",
    feature="assistant_reply",
)

message = anthropic.messages.create(
    model="example-anthropic-model",
    max_tokens=1_024,
    messages=[{"role": "user", "content": "Hello"}],
)

Anthropic streams read input usage from message_start and output usage from message_delta events.

Wrapper arguments

Argument	Required	Default	Description
`client`	yes	—	OpenAI or Anthropic client instance.
`nozle`	yes	—	Configured `Nozle` client.
`customer_id`	yes	—	Customer passed to `track()`.
`metric_code`	no	`llm_tokens`	Event code.
`cost_meter_code`	no	`None`	Cost Event Meter code. When set, emits categorized token Cost Events linked to the Feature Event.
`feature`	no	`None`	Optional event property.

Tracked properties

{
  "provider": "openai",
  "model": "example-chat-model",
  "input_tokens": 320,
  "output_tokens": 84,
  "latency_ms": 742,
  "feature": "assistant_reply"
}

The Feature Event preserves total input and output counts. Detailed Cost Events use canonical properties { tokens, provider, model, type } and one of these non-zero categories:

OpenAI: input, cached_input, output, and reasoning.
Anthropic: input, cached_input, cache_write, and output.

Cost calculation remains server-side through the ai_tokens Cost Event Meter and effective-dated provider/model/category Cost Rules.

Failure behavior

The usage event’s transaction_id is llm-<format>-<response id> when the response has an id, so the same response is never recorded twice; otherwise one is generated. It is the parent_transaction_id of every detailed Cost Event. Parent and child events may therefore arrive out of order. Tracking failures do not replace a successful provider result; the SDK emits NozleTrackingWarning. The warning names only the exception type, not the cause, for example Nozle tracking failed after a successful LLM response (NozleAPIError). A customer with several active subscriptions makes every wrapped call emit it. Under python -W error, the SDK swallows the warning instead of raising it. The synchronous wrapper tracks inline: each wrapped call waits for one tracking request (about 255 ms observed). With cost_meter_code, it sends several requests per call. For async provider calls, synchronous Nozle tracking runs in a worker thread through asyncio.to_thread(). The wrapper does not expose subscription_id, so track() resolves the customer’s single active subscription. Use manual queued tracking when you need to choose the transaction identifier or coordinate delivery through your own queue.

response = provider_call()

nozle.track(
    "workspace_123",
    "llm_tokens",
    metadata={
        "model": response.model,
        "input_tokens": response.input_tokens,
        "output_tokens": response.output_tokens,
    },
    subscription_id="workspace_123_subscription",
    transaction_id=f"llm:{response.id}:usage",
)

Manual cost events

Use nozle.cost_events.track() for providers without a wrapper and for cost-only tracking. A Cost Event never bills the customer.

nozle.cost_events.track(
    cost_meter_code="ai_tokens",
    external_customer_id="workspace_123",        # or parent_transaction_id=<Feature Event id>
    cost_event_id=f"turn:{turn.id}:input",       # stable per unit, reused on retry
    properties={"tokens": 900, "provider": "openai", "model": "configured-model-a", "type": "input"},
    timestamp=turn.created_at.timestamp(),       # a float, Unix seconds
)

Argument	Description
`cost_meter_code`	Required. Cost Event Meter code.
`parent_transaction_id`	Feature Event `transaction_id` to link to.
`external_customer_id`	Customer ID. Pass this or `parent_transaction_id`.
`cost_event_id`	Stable event ID. Generated when omitted.
`request_id`	Optional provider request ID.
`operation_key`	Optional operation label.
`properties`	JSON-compatible properties, for example `{tokens, provider, model, type}`.
`timestamp`	Optional `float` of Unix seconds. An ISO string returns `400 invalid request body`.

Requires an sk_ key.
Without parent_transaction_id or external_customer_id, it raises NozleValidationError before any request.
Returns {"status": "accepted", "cost_event_id": ...} after a 202.
The same cost_event_id sent twice returns 202 both times. Processing de-duplicates it.

An unknown cost_meter_code is accepted with 202. The event is then marked uncosted with unknown_cost_event_meter and listed in the Uncosted queue, and its cost is not counted until you fix the meter and rate it again. Check the code against your Cost Event Meters.

Setup

Billing

Customers

Entitlements

Margin Intelligence

LLM Usage

LLM auto-capture

Capture any client

One client for every customer

Usage you read yourself

Client wrappers

OpenAI

OpenAI streaming

Anthropic

Wrapper arguments

Tracked properties

Failure behavior

Manual cost events

​Capture any client

​One client for every customer

​Usage you read yourself

​Client wrappers

​OpenAI

​OpenAI streaming

​Anthropic

​Wrapper arguments

​Tracked properties

​Failure behavior

​Manual cost events

Capture any client

One client for every customer

Usage you read yourself

Client wrappers

OpenAI

OpenAI streaming

Anthropic

Wrapper arguments

Tracked properties

Failure behavior

Manual cost events