LLM auto-capture

nozle.captureFetch() returns a fetch that records the token usage of every successful LLM response it carries. Pass it to any client that accepts a custom fetch: the OpenAI and Anthropic SDKs, Vercel AI SDK providers, LangChain, or your own calls. Requests and responses pass through unchanged, and prompts and completions are never sent to Nozle. captureFetch() and recordUsage() require @nozle-js/node 0.13.0. The client wrappers are available in earlier versions. Usage is recognised by the shape of the response, not by provider name:

Response shape	Covers
`usage.prompt_tokens` / `completion_tokens`	OpenAI chat completions and any OpenAI-compatible API (OpenRouter, Groq, Azure OpenAI, vLLM, Together, Ollama)
`usage.input_tokens` / `output_tokens`	The OpenAI Responses API, and Anthropic messages (with `type: "message"` or cache token fields)
`usageMetadata`	Gemini `generateContent`

JSON responses and streams are both read. A stream is read in the background as your app reads it; usage seen before the stream ends or is aborted still counts.

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

import OpenAI from 'openai'
import { Nozle } from '@nozle-js/node'

const nozle = new Nozle() // reads NOZLE_SECRET_KEY

const openai = new OpenAI({
  fetch: nozle.captureFetch({ customerId: 'workspace_123', featureCode: 'llm_tokens' }),
})

The same fetch works with other clients:

import Anthropic from '@anthropic-ai/sdk'
import { createOpenAI } from '@ai-sdk/openai'

const fetch = nozle.captureFetch({ customerId: 'workspace_123' })
const anthropic = new Anthropic({ fetch })
const provider = createOpenAI({ fetch }) // Vercel AI SDK

One client for every customer

Set the customer per request instead of per client. customerId can be a function, called with each 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.

const openai = new OpenAI({ fetch: nozle.captureFetch() })

await openai.chat.completions.create(
  { model: 'example-chat-model', messages },
  { headers: { 'X-Nozle-Customer-Id': workspace.id, 'X-Nozle-Feature': 'assistant_reply' } },
)

A request without a customer passes through and nothing is recorded.

`CaptureFetchOptions`

Field	Type	Description
`customerId`	`string \| (request) => string \| undefined`	Customer to bill. The `X-Nozle-Customer-Id` header wins.
`featureCode`	`string`	Feature code of the usage event. Default `llm_tokens`.
`feature`	`string`	Stored as the `feature` property. The `X-Nozle-Feature` header wins.
`costMeterCode`	`string`	Also send one Cost Event per token category to this Cost Event Meter.
`includeStreamUsage`	`boolean`	Default `true`: chat completion streams are sent with `stream_options.include_usage`, which they otherwise leave out. Set `false` for a server that rejects the field.
`onError`	`(error) => void`	Called when usage could not be read or recorded, and once per event code with `code: "feature_not_found"` when no Feature has that code (the usage is then stored but not billed). The provider response is never affected.

The second argument of captureFetch is the fetch to wrap; it defaults to the global fetch.

Usage you read yourself

For a client that cannot take a custom fetch, record the usage after the call. recordUsage rejects if the usage could not be recorded.

await nozle.recordUsage({
  customerId: 'workspace_123',
  model: response.model,
  requestId: response.id,          // makes the event id stable
  inputTokens: 1_200,              // all input, including cached input
  cachedInputTokens: 300,
  outputTokens: 400,               // all output, including reasoning
  reasoningTokens: 100,
  provider: 'openai',
})

Client wrappers

wrapOpenAI and wrapAnthropic record the usage of one client’s create method instead. They are kept for existing integrations; captureFetch covers more APIs and providers.

From 0.13.1, wrapOpenAI and wrapAnthropic return a new 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 customerId, so a server can keep one provider client and wrap it per request. Views over the same client are independent, including concurrent calls, 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.

const openai = new OpenAI()

app.post('/chat', async (req) => {
  const client = wrapOpenAI(openai, nozle, { customerId: req.team.id })
  return client.chat.completions.create({ model: 'example-chat-model', messages: req.body.messages })
})

The wrapped client keeps the full SDK surface. create returns the SDK’s own APIPromise or Stream, so withResponse(), asResponse(), chat.completions.parse(), messages.stream() / finalMessage(), stream.controller and toReadableStream() work as without the wrapper. Usage is recorded once, when your code reads the response. asResponse() leaves the body to you, so nothing is recorded for it. A provider error rejects to your code only and records nothing. openai and @anthropic-ai/sdk are optional peer dependencies of @nozle-js/node. Install the one you wrap.

OpenAI

npm install openai

import OpenAI from 'openai'
import { wrapOpenAI } from '@nozle-js/node'

const nozle = new Nozle()

const openai = wrapOpenAI(new OpenAI(), nozle, {
  customerId: 'workspace_123',
  metricCode: 'llm_tokens',
  costMeterCode: 'ai_tokens',
  feature: 'assistant_reply',
})

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

OpenAI streaming

The wrapper sets stream_options.include_usage to true for streaming calls and reads the final usage-bearing chunk. It overwrites only include_usage: other stream_options keys are kept, and your own object is not mutated.

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

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '')
}

A stream is recorded when it is fully iterated. If you stop reading early (break or return()), or read the stream through tee(), the wrapper sends no Feature Event and no Cost Events, for OpenAI and Anthropic. Only chat.completions.create is wrapped for OpenAI. The Responses API is not wrapped.

Anthropic

npm install @anthropic-ai/sdk

import Anthropic from '@anthropic-ai/sdk'
import { wrapAnthropic } from '@nozle-js/node'

const anthropic = wrapAnthropic(new Anthropic(), nozle, {
  customerId: 'workspace_123',
  metricCode: 'llm_tokens',
  costMeterCode: 'ai_tokens',
  feature: 'assistant_reply',
})

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

For Anthropic streams, the wrapper reads input usage from message_start and output usage from message_delta events. messages.stream() and finalMessage() read the whole stream, so they record usage once.

`WrapOptions`

Field	Type	Required	Description
`customerId`	`string`	yes	Customer passed to `nozle.track()`. Fixed at wrap time and used for every call; a per-call `user` is ignored.
`metricCode`	`string`	no	Event code; defaults to `llm_tokens`.
`costMeterCode`	`string`	no	Cost Event Meter code. When set, emits categorized token Cost Events linked to the Feature Event.
`feature`	`string`	no	Included as a `feature` event property.
`onError`	`(error) => void`	no	Called when usage could not be recorded, and once per event code with `code: "feature_not_found"` when no Feature has that code. Without it these failures are silent.

Event properties

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

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

OpenAI-compatible and Gemini: input, cached_input, output, and reasoning.
Anthropic: input, cached_input, cache_write, and output.

provider is the response format (openai, anthropic or gemini); provider_host is the host the request went to, so an OpenAI-compatible provider is told apart by its host. provider_host is sent by captureFetch only. Cost calculation remains server-side. Configure the ai_tokens Cost Event Meter and effective-dated provider/model/category Cost Rules to interpret these events.

Delivery behavior

The usage event’s transaction_id is llm-<format>-<response id>, for example llm-openai-chatcmpl-123, so the same response is never recorded twice. A response without an id gets a generated one. The same id is the parent_transaction_id of every detailed Cost Event, so parent and child events may arrive in any order. Recording runs without delaying the provider response, and a recording failure never replaces a successful provider result.

Without onError, wrapOpenAI and wrapAnthropic record failures silently: no log line and no unhandled rejection, including for a customer with no active subscription. Pass onError, or use recordUsage, when you need to know.

For workflows requiring durable delivery, explicit transaction IDs, or strict error handling, track manually through your queue instead of relying on the wrapper.

const response = await providerCall()

await nozle.track(
  'workspace_123',
  'llm_tokens',
  {
    model: response.model,
    input_tokens: response.inputTokens,
    output_tokens: response.outputTokens,
  },
  {
    subscriptionId: 'workspace_123_subscription',
    transactionId: `llm:${response.id}:usage`,
  },
)

Manual cost events

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

await nozle.costEvents.track({
  costMeterCode: 'ai_tokens',
  externalCustomerId: 'workspace_123',      // or parentTransactionId
  costEventId: `turn:${turn.id}:input`,     // stable per unit, reused on retry
  properties: { tokens: 900, provider: 'openai', model: 'example-chat-model', type: 'input' },
  timestamp: turn.createdAt.getTime() / 1000, // a number of Unix seconds
})

Requires a secret sk_ key.
Requires parentTransactionId or externalCustomerId. Without either, it throws before sending.
timestamp is a number of Unix seconds. An ISO string returns 400 Bad Request.
Returns { status: 'accepted', cost_event_id }.
nozle.costEvents.createCostEventId() returns a UUIDv7. The SDK generates one when costEventId is omitted.
Posts to the Engine host (baseUrl).
The same costEventId sent again is accepted with 202 and de-duplicated during processing.
Send one event per non-zero token type: input, cached_input, cache_write, output, or reasoning.

An unknown costMeterCode 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

`CaptureFetchOptions`

Usage you read yourself

Client wrappers

OpenAI

OpenAI streaming

Anthropic

`WrapOptions`

Event properties

Delivery behavior

Manual cost events

​Capture any client

​One client for every customer

​CaptureFetchOptions

​Usage you read yourself

​Client wrappers

​OpenAI

​OpenAI streaming

​Anthropic

​WrapOptions

​Event properties

​Delivery behavior

​Manual cost events

Capture any client

One client for every customer

`CaptureFetchOptions`

Usage you read yourself

Client wrappers

OpenAI

OpenAI streaming

Anthropic

`WrapOptions`

Event properties

Delivery behavior

Manual cost events