Track Token Usage
Records AI token usage for a customer and returns the updated AI credit balance.
Use this after an LLM request when you have input and output token counts. Autumn converts token usage to a dollar amount using the configured model pricing and markup, then tracks that value against the customer’s AI credit system.
model_id must use provider/model format, matching the provider and model keys from Models.dev. For providers with nested model paths (like OpenRouter), include the full path: openrouter/anthropic/claude-opus-4.6. The first path segment is the provider key used for provider-level markup lookup.
Common Use Cases
Token Pools
Each token parameter is an exclusive pool — no token should be counted in more than one. Each pool is billed at the model’s published rate for that pool, falling back to the text input/output rate when the model has none.Markup Resolution
Markups are optional — the credit system’s default markup applies unless overridden per provider or per model. With no markups set, the Models.dev base cost is charged as-is. A markup of-100 makes the model free — the usage event is still recorded, but nothing is deducted. See AI Credit Systems for configuration.
Body Parameters
Response
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Body
The ID of the customer.
The AI model as '[provider]/[model]' (e.g. 'anthropic/claude-opus-4-8', 'openrouter/openai/gpt-4o'). The provider is the first path segment and must match a provider + model key in models.dev.
Number of non-cached text input tokens consumed. Exclusive of cache and audio token pools.
0 <= x <= 9007199254740991Number of text output tokens consumed. Exclusive of the reasoning and audio output pools.
0 <= x <= 9007199254740991The ID of the entity for entity-scoped balances.
The ID of the AI credit system feature. Auto-detected from the customer's entitlements if omitted — only required when a customer has multiple AI credit systems.
Number of cached input tokens read.
0 <= x <= 9007199254740991Number of input tokens written to the cache.
0 <= x <= 9007199254740991Number of audio input tokens consumed.
0 <= x <= 9007199254740991Number of audio output tokens generated.
0 <= x <= 9007199254740991Number of reasoning tokens generated.
0 <= x <= 9007199254740991Additional properties to attach to this usage event.
Unix timestamp in milliseconds to use for the usage event. Defaults to the current time.
0 < x <= 9007199254740991How to handle usage that exceeds the available balance. "cap" (default) deducts only what fits, stopping at zero. "overflow" deducts the full value: the balance can go negative and usage limits do not clamp the deduction, though spend limits still apply.
cap, overflow If true, enqueue the event for asynchronous processing and return 204 immediately. The response will not include balance information.
Response
OK
The ID of the customer whose usage was tracked.
The amount of usage that was recorded.
The updated balance for the tracked feature. Null if tracking by event_name that affects multiple features.
The ID of the entity, if entity-scoped tracking was performed.
The event name that was tracked, if event_name was used instead of feature_id.
Map of feature_id to updated balance for the tracked feature and any related features (e.g. linked credit systems). Value is null when the customer has no balance for that feature.
Per-balance breakdown of what this event deducted. A single event can consume from multiple balance rows when credit systems or rollovers are involved; this surfaces each one so callers can build per-feature usage views without polling.