Usage metering for AI agents - Stigg Documentation

Wrap the client you already use to call an LLM provider or an LLM gateway, and every completed call is metered: the usage the vendor reported is read from the response and sent to Stigg, attributed to the customer (and optionally the agent) that made it. There is no usage to count in your own code, and nothing changes in how you call the model.

Supported providers and gateways

stigg.wrap(client) recognizes each of these from the client object itself, so you do not name the vendor. Each vendor’s page shows how to wrap it and exactly what is reported.

LLM providers

Anthropic

Messages API, streaming included, with the full prompt-caching breakdown

OpenAI

Chat Completions and Responses API, streaming included

Google Gemini

One-shot calls and chats, streaming included, with thinking tokens reported separately

Mistral

Chat, fill-in-the-middle and agent calls, streaming included

Groq

Groq’s own client or the OpenAI client, reported under Groq’s own event name

xAI

Grok models, through the OpenAI client

DeepSeek

DeepSeek’s own models, through the OpenAI client

Perplexity

Models with built-in web search, through the OpenAI client

Together AI

A large catalog of open-source models, through the OpenAI client

Fireworks AI

Open-source and fine-tuned models, through the OpenAI client

Ollama

Models you host yourself: meter and limit your own capacity

vLLM

Your self-hosted model server, through the OpenAI client

TypeSafe

Jev, a model that answers typed questions about your data (yes or no, choice or score) in one call

LLM gateways

OpenRouter

Reports the credits actually charged and the model that actually served, through the OpenRouter or OpenAI client

LiteLLM Proxy

Self-hosted or cloud gateway: reports the cost LiteLLM computed for each call

Amazon Bedrock

The Converse API, for every model Bedrock serves

Cloudflare

AI Gateway and Workers AI, with cache hits left unbilled and the model that served

Databricks

Model serving endpoints, with the model that actually answered each call

Bring your own vendor

Any OpenAI-compatible API

Point the OpenAI client at any endpoint in OpenAI’s format and it is metered with no extra code

Custom adapter

Any other model or API, including your own: describe where its usage is and the SDK does the rest

How usage is reported

Same names as the vendor. Each metric keeps the name the vendor uses, such as input_tokens for Anthropic, prompt_tokens for OpenAI or promptTokenCount for Gemini. You can compare the numbers in Stigg directly with the vendor’s own usage reports, such as its usage dashboard.
A total, and its parts. Every vendor also reports a total: the vendor’s own where it publishes one, such as total_tokens or totalTokenCount, and otherwise the sum of the parts, added up by the SDK (Anthropic, Ollama and TypeSafe). The total includes the other counters, so price the total or the parts, never both.
What a gateway charged, where it says. OpenRouter and LiteLLM Proxy also report cost, what the gateway actually charged for the call, and the model that served it. See Charging by tokens or by cost.
Every usage field, not just the named metrics. Each event also includes every usage field the vendor returned, with a raw. prefix (raw.<field name>). If a vendor adds a field the SDK does not report as a metric yet, you can build a meter on it without waiting for an SDK update.
No prompts or responses. Only usage numbers are sent to Stigg. The text of your prompts and the model’s responses never leaves your application.

Every completed call produces one measurement: the usage the vendor reported, under the vendor’s own field names. The SDK turns that measurement into metrics with a usage mapper, and reports them to Stigg through one of two ingest modes.

Ingest modes

The SDK reports usage in one of Stigg’s two standard ways, chosen by the ingest mode:

Mode	Reports usage as	Use it for
`async` (default)	Raw events: one event per call, with every metric as a field	High-volume traffic and token pass-through pricing
`sync`	Calculated usage: one report per metric	Balances that must reflect each call before the next check, such as credits that burn down in real time

For how the two differ, including how quickly limits are enforced, see Supported usage sources. You can set the mode for the whole SDK, for one wrapped client, or for a single call. A more specific setting takes precedence:

const stigg = new StiggAgentSDK(process.env.STIGG_SERVER_API_KEY, { ingest: 'sync' });

const anthropic = stigg.wrap(new Anthropic(), {
  stiggContext: { ingestMode: 'sync' },
});

await anthropic.messages.create({
  ...params,
  stiggContext: { ingestMode: 'sync' },
});

What is specific to the SDK:

Usage reported to a feature in sync mode must be a whole number. Stigg’s usage API accepts only whole numbers, so a fractional value is not reported and the failure is passed to onError. A credit type accepts fractional amounts in either mode, and so does an event in async mode.
Credits you calculate in code are deducted directly. Usually the SDK reports raw metrics, such as token counts, and Stigg converts them into credits using your credit consumption settings. If you convert usage into credits yourself with a usage mapper, the SDK deducts the result straight from the credit balance, in either mode, so it is not converted twice. It recognizes these credits by name: the mapper’s output must use the ID of the credit type the call is checked against. For example, a mapper that outputs { credits: 3 } for a call checked against { currencyId: 'credits' } deducts 3 credits. The ID must match exactly: a mapper that outputs { data_credit: 3 } for a call checked against { currencyId: 'credits' } reports a feature named data_credit, which needs a meter like any other feature.
In async mode, deducted credits can take a moment to show. The deduction is applied to the balance asynchronously, so a check made right after a call may not include it yet. Use sync when each call must be deducted before the next check.

Configuring meters for async events

In async mode each call becomes one event:

The event name is the vendor call that produced it, for example anthropic.messages.create. Each vendor’s event names are listed on its page. Usage from a gateway you operate is named <vendor>.proxied, or the event you pass to ingestFromHeaders().
Every metric is a field on the event, under the names on the provider’s page.

Override the name with stiggContext.eventName, for example eventName: { name: 'llm.call' }, to put several vendors behind one meter. To meter a metric, create a metered feature with a raw-events meter that filters on the event name and sums the field. For example, output tokens from Anthropic:

{
  "aggregation": { "function": "SUM", "field": "output_tokens" },
  "filters": [
    { "conditions": [{ "field": "eventName", "operation": "EQUALS", "value": "anthropic.messages.create" }] }
  ]
}

One event can feed any number of meters, so you can add an input-token feature, a cached-token feature, or a per-model breakdown later without changing code. For example, an OpenRouter call made by an agent produces an event like this:

{
  "customerId": "customer-acme",
  "eventName": "openrouter.chat.completions.create",
  "idempotencyKey": "gen-1760262400-a1b2c3",
  "dimensions": {
    "prompt_tokens": 1200,
    "completion_tokens": 350,
    "cached_tokens": 800,
    "total_tokens": 1550,
    "cost": 4210,
    "model": "anthropic/claude-sonnet-5",
    "agentId": "agent-support-bot",
    "raw.prompt_tokens": 1200,
    "raw.completion_tokens": 350,
    "raw.total_tokens": 1550,
    "raw.cost": 0.00421
  }
}

The event follows Stigg’s standard raw event format, sent with the Report events API. Its dimensions hold:

The metrics, under the names on the provider’s page. Here cost is in millionths of an OpenRouter credit.
Your own dimensions, and the agent ID under your agent type’s attribution key (here agentId) when you set one. Use them as meter filters or for governance attribution.
For gateways, the model that served the call.
Every usage field the vendor returned, with a raw. prefix. Nested fields are flattened into single values.

You can see your own events under Usage events in the Stigg app.

An event whose name matches no meter is accepted and meters nothing. The events API returns only an acknowledgement, so nothing reports the mismatch. Configure the meter first, and check the first events under Usage events in the Stigg app. See Viewing usage events.

Usage mappers

By default the SDK reports exactly the usage the vendor returned, under the vendor’s own metric names, so the numbers in Stigg match the vendor’s own usage reports. This needs no configuration. Each vendor’s metrics are listed on its page. To report something else, set stiggContext.usageMapper to one of the mappers below, or to your own. Set it on wrap() as the client’s default, or pass it with each call to override the default for that call.

Weighted credits

Converts each call’s usage into credits in your code, using a rate table, and deducts them straight from the credit balance. Usually you do not need this. The standard way to charge credits for tokens is in Stigg: create a metered feature for each token metric and set its credit cost in the credit type’s Credit consumption settings. See Credits. Use weighted credits instead when:

You want the rates in code, for example to charge different rates per model by passing a different mapper in each call’s stiggContext, instead of creating a feature for each case in Stigg.
You want to skip meters. Credits calculated in code are deducted straight from the balance, with no metered feature or meter to configure. With sync mode, the next check already includes them.

weightedMetrics() turns a rate table into a mapper that reports one number, typically to a credit type or a single metered feature:

import { anthropicRecipe, weightedMetrics } from '@stigg/agent-sdk-js';

const anthropic = stigg.wrap(new Anthropic(), {
  stiggContext: {
    entitlement: { currencyId: 'credits' },
    // 1 credit per 1,000 input tokens, 5 per 1,000 output tokens. Cache reads are free.
    usageMapper: weightedMetrics(
      anthropicRecipe,
      'credits',
      { input_tokens: 1, output_tokens: 5 },
      { per: 1_000 },
    ),
  },
});

The table is typed against the recipe’s own metric names, so a typo does not compile.
A metric left out of the table is free.
The total is not rounded. A credit type accepts fractional amounts, so a call worth a fifth of a credit costs a fifth of a credit. When the target is a metered feature in sync mode, which accepts only whole numbers, choose rates and a per that divide evenly, or round in your own mapper.
A call that measured nothing reports nothing.

For a single rate across all token types, unitsPerTokens('credits', 1_000) reports one unit per 1,000 tokens of any kind. It does not round either.

A call attributed to an agent is the exception: Governance counts agent and team usage in whole units, so the SDK rounds the amount up to the next whole unit and logs that it did. See Usage governance.

A mapper can also be passed with each call instead of on wrap(), like any other stiggContext field. This keeps the wrapped client generic, for example to charge a different rate per model:

const anthropic = stigg.wrap(new Anthropic());

const rates = {
  'claude-opus-5': weightedMetrics(anthropicRecipe, 'credits', { input_tokens: 15, output_tokens: 75 }, { per: 1_000 }),
  'claude-haiku-5': weightedMetrics(anthropicRecipe, 'credits', { input_tokens: 1, output_tokens: 5 }, { per: 1_000 }),
};

const model = 'claude-haiku-5';
const message = await anthropic.messages.create({
  model,
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Summarize this ticket' }],
  stiggContext: {
    customerId: 'customer-acme',
    entitlement: { currencyId: 'credits' },
    usageMapper: rates[model],
  },
});

Normalized metrics across vendors

Vendors disagree on whether cached tokens are already counted inside the input total: OpenAI and Gemini include them, while Anthropic and Amazon Bedrock count cache reads and writes separately. Each vendor’s page says which applies under What is reported. To price every vendor with one set of features, use normalizedMetrics. It reports four non-overlapping counters under SDK-owned names: stigg_input_tokens, stigg_output_tokens, stigg_cache_read_tokens and stigg_cache_creation_tokens.

import { normalizedMetrics } from '@stigg/agent-sdk-js';

stigg.wrap(client, { stiggContext: { usageMapper: normalizedMetrics } });

Your own mapper

When none of the built-in mappers fits, write your own. A mapper is a plain function: it receives the usage the recipe measured for a call, and returns what to report, as a { featureOrCurrencyId: value } record. Each recipe exports a type for what it receives:

import type { AnthropicMetrics, Metrics } from '@stigg/agent-sdk-js';

const dataCredits = ({ metrics = {} }: { metrics?: AnthropicMetrics }): Metrics => {
  const weighted = (metrics.output_tokens ?? 0) * 5 + (metrics.input_tokens ?? 0);
  return weighted > 0 ? { data_credit: Math.ceil(weighted / 100) } : {};
};

Pass it as the usageMapper:

const anthropic = stigg.wrap(new Anthropic(), {
  stiggContext: { usageMapper: dataCredits },
});

Every counter is optional, because a vendor omits a counter (such as cache reads) when it is zero. A value reported to a feature in sync mode must be a whole number. The mapper also receives the rest of the measurement: usage (the four normalized token counters), dimensions, and estimated. estimated is true when a count is the SDK’s estimate rather than the vendor’s. This happens when a streamed Anthropic call is stopped before it finishes: Anthropic reports the output count only at the end of the stream, so the SDK estimates the output from the text received so far, at about four characters per token. To meter only counts the vendor reported, return {} when estimated is set:

import type { Measurement, Metrics } from '@stigg/agent-sdk-js';

const vendorCountsOnly = (measurement: Measurement): Metrics =>
  measurement.estimated ? {} : (measurement.metrics ?? {});

The Agent SDK is open source under the MIT license. If your mapper would be useful to others, for example a pricing scheme common in your industry, contribute it to the Agent SDK on GitHub so other developers can use it too.

Metering through a gateway

An LLM gateway sits between your code and the LLM providers. It lets you:

Work with one API across many LLM providers, often with failover, caching and routing between models.
Set up one commercial agreement, with the gateway, while still using models from many providers.

When you call a gateway, you wrap the client you use to call it, the same way as for an LLM provider. Each call is metered like any other, and some gateways also report what only the gateway knows: what the call really cost, and which model really served it. What each gateway reports is on its page.

Charging by tokens or by cost

An OpenRouter or LiteLLM Proxy call reports two kinds of numbers: the token counts, and cost, what the gateway charged for the call. You choose which one usage is measured in:

Tokens, to treat calls the same way whether they go straight to a provider or through a gateway. Meter the token metrics.
cost, to follow what the gateway actually charged, for example to pass it on with your margin. Meter the cost metric.

Either one can drive any pricing model in Stigg. Customers can be invoiced for their usage, or they can pay upfront for credits, through a top-up or a plan that includes credits, and each call burns credits from their balance. Set it up in Stigg as usual: create a metered feature for the metric, add it to your plans, and for credits, map the feature to a credit cost in the credit type’s Credit consumption settings. See Configuring meters for async events and Credits.

Optional: convert cost into credits in your code

Instead of mapping a feature to credits in Stigg, the SDK can convert usage into credits before it is reported, and deduct them straight from the credit balance. Use this only when the conversion has to live in code. See Weighted credits.

import { openrouterRecipe, weightedMetrics } from '@stigg/agent-sdk-js';

const recipe = openrouterRecipe();

const router = stigg.wrap(new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY }), {
  recipe,
  stiggContext: {
    entitlement: { currencyId: 'credits' },
    // 1 Stigg credit per 1,000 millionths of an OpenRouter credit.
    // Each call still passes its own customerId.
    usageMapper: weightedMetrics(recipe, 'credits', { cost: 1 }, { per: 1_000 }),
  },
});

Routing drift

The model dimension records the model that served, not the one you asked for. Filter or group a meter by it in Stigg to see how often your traffic falls back, and how that changes your cost.

A gateway you operate

A proxy you run is a separate process. It sees requests, not the customer or agent behind them, and the customer’s budget lives in your application. So the work splits across the boundary:

Your application checks the budget in-process, as usual, and sends attribution with the request as x-stigg-* headers.
Your proxy forwards the request, reads usage off the provider’s response, and reports it with stigg.ingestFromHeaders().

Governance decisions never leave your application. The proxy only meters.

In your application

const headers = stigg.governanceHeaders({
  customerId: 'customer-acme',
  agentId: 'drafter',
  attributionKey: 'agentId',
});
// { 'x-stigg-customer-id': 'customer-acme',
//   'x-stigg-dimensions': '{"agentId":"drafter"}',
//   'x-stigg-attribution-key': 'agentId',
//   'x-stigg-run-id': '...' }

await fetch(`${PROXY_URL}/v1/chat/completions`, {
  method: 'POST',
  headers: { 'content-type': 'application/json', ...headers },
  body: JSON.stringify(params),
});

A wrapped client can build the same headers with its own stigg.headers(context).

In your proxy

import { StiggAgentSDK } from '@stigg/agent-sdk-js';

const stigg = new StiggAgentSDK(process.env.STIGG_SERVER_API_KEY);

// Inside your request handler, after the upstream call returns:
const completion = await upstream.chat.completions.create(params);

await stigg.ingestFromHeaders(req.headers, {
  vendor: 'openai',                 // the response shape the proxy observed
  usage: completion.usage,
  idempotencyKey: completion.id,    // the upstream request ID
  entitlement: { currencyId: 'credits' },
});

Header	Content
`x-stigg-customer-id`	The customer the request belongs to. Requests without it are not attributed.
`x-stigg-dimensions`	A JSON object of attribution dimensions, such as the agent ID.
`x-stigg-attribution-key`	Which key in `x-stigg-dimensions` holds the agent ID, when the context includes an `agentId`.
`x-stigg-run-id`	A correlation ID for work that spans processes.

vendor is one of anthropic, openai (Chat Completions), openai-responses, gemini or typesafe. It is named rather than guessed because several vendors share field names (input_tokens appears in both Anthropic and OpenAI Responses usage), and a wrong guess would report to the wrong meter. If you omit it, pass a metrics mapper so the SDK knows what to report.

Do not meter the same traffic in both places. If your application wraps its client and your proxy calls ingestFromHeaders() for the same requests, the usage is reported twice. Wrap in the application for calls that return into your process, and use the header path only for traffic the application cannot meter itself.

Idempotency

Every report carries an idempotency key, so a retried report is not counted twice:

When the vendor returns a request ID that is stable across its own retries (for example an OpenRouter generation ID), that ID is used.
Otherwise the SDK generates one per call.
Set stiggContext.idempotencyKey on a call to choose your own, for example when you resume a stream and report the same turn again.

In sync mode each metric is keyed separately as <key>:<metric>.

Errors and flushing

Reporting never breaks the call. If a report fails, the response is still returned and the failure is passed to onError:

const stigg = new StiggAgentSDK(process.env.STIGG_SERVER_API_KEY, {
  onError: (error, context) => {
    // context: { operation, customerId, idempotencyKey, runId }
    myTelemetry.capture(error, context);
  },
});

By default onError logs a warning, so failures are visible before you wire it up. Reports are sent in the background. In serverless functions, request-scoped workers and CLIs, wait for them to be sent before the process exits:

await anthropic.stigg.flush();          // one wrapped client
await stigg.flush({ close: true });     // every client, then release connections

flush() returns a summary of what was reported: the number of checks and ingests, failures, and the totals per metric.

Troubleshooting

The credit balance does not go down

A credit balance only goes down when the feature you report is mapped to that credit type in Stigg. If it is not, every call succeeds and every report is accepted, but the balance never changes. In sync mode the SDK detects this from Stigg’s response and logs:

[stigg] reported input_tokens but the response carried no credit balance - this feature is not
mapped to credits, so the budget this run checks against will never drain.

Fix it by mapping the feature to the currency, or by reporting to the currency directly with a weighted mapper.

​Supported providers and gateways

​LLM providers

Anthropic

OpenAI

Google Gemini

Mistral

Groq

xAI

DeepSeek

Perplexity

Together AI

Fireworks AI

Ollama

vLLM

TypeSafe

​LLM gateways

OpenRouter

LiteLLM Proxy

Amazon Bedrock

Cloudflare

Databricks

​Bring your own vendor

Any OpenAI-compatible API

Custom adapter

​How usage is reported

​Ingest modes

​Configuring meters for async events

​Usage mappers

​Weighted credits

​Normalized metrics across vendors

​Your own mapper

​Metering through a gateway

​Charging by tokens or by cost

​Routing drift

​A gateway you operate

​In your application

​In your proxy

​Idempotency

​Errors and flushing

​Troubleshooting

​The credit balance does not go down

Supported providers and gateways

LLM providers

LLM gateways

Bring your own vendor

How usage is reported

Ingest modes

Configuring meters for async events

Usage mappers

Weighted credits

Normalized metrics across vendors

Your own mapper

Metering through a gateway

Charging by tokens or by cost

Routing drift

A gateway you operate

In your application

In your proxy

Idempotency

Errors and flushing

Troubleshooting

The credit balance does not go down