Skip to main content
POST
/
v1
/
balances.track_tokens
Typescript (SDK)
import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.trackTokens({
  customerId: "cus_123",
  featureId: "ai_credits",
  modelId: "anthropic/claude-sonnet-4-20250514",
  inputTokens: 1000,
  outputTokens: 500,
});
{
  "customer_id": "cus_123",
  "value": 0.06,
  "balance": {
    "feature_id": "ai_credits",
    "granted": 10.00,
    "remaining": 9.94,
    "usage": 0.06,
    "unlimited": false,
    "overage_allowed": false,
    "next_reset_at": 1773851121437,
    "breakdown": [
      {
        "id": "cus_ent_abc123",
        "plan_id": "pro_plan",
        "included_grant": 10.00,
        "prepaid_grant": 0,
        "remaining": 9.94,
        "usage": 0.06,
        "unlimited": false,
        "reset": {
          "interval": "month",
          "resets_at": 1773851121437
        },
        "price": null,
        "expires_at": null
      }
    ]
  }
}
Track AI token usage against a customer’s AI credit system balance. Converts token counts to a dollar cost using Models.dev pricing and your configured markup, then deducts from the customer’s credit balance.
The 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

await autumn.balances.trackTokens({
  customerId: "cus_123",
  modelId: "anthropic/claude-opus-4-6",
  inputTokens: 1000,
  outputTokens: 500
});

​
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.
If you pass a provider’s raw totals (e.g. OpenAI’s prompt_tokens and completion_tokens), subtract the cache and reasoning counts first — otherwise those tokens are billed twice. The @useautumn/gateway wrappers (AI SDK, OpenRouter) do this normalization for you.

​
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.
feature_id is auto-detected when the customer has exactly one AI credit system. The request fails if the customer has none, or has more than one and feature_id is omitted.

​
Body Parameters

​
Response

{
  "customer_id": "cus_123",
  "value": 0.06,
  "balance": {
    "feature_id": "ai_credits",
    "granted": 10.00,
    "remaining": 9.94,
    "usage": 0.06,
    "unlimited": false,
    "overage_allowed": false,
    "next_reset_at": 1773851121437,
    "breakdown": [
      {
        "id": "cus_ent_abc123",
        "plan_id": "pro_plan",
        "included_grant": 10.00,
        "prepaid_grant": 0,
        "remaining": 9.94,
        "usage": 0.06,
        "unlimited": false,
        "reset": {
          "interval": "month",
          "resets_at": 1773851121437
        },
        "price": null,
        "expires_at": null
      }
    ]
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-api-version
string
default:2.3.0
required

Body

application/json
​
customer_id
string
required

The ID of the customer.

​
model_id
string
required

The AI model as '/' (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.

​
input_tokens
integer
required

Number of non-cached text input tokens consumed. Exclusive of cache and audio token pools.

Required range: 0 <= x <= 9007199254740991
​
output_tokens
integer
required

Number of text output tokens consumed. Exclusive of the reasoning and audio output pools.

Required range: 0 <= x <= 9007199254740991
​
entity_id
string

The ID of the entity for entity-scoped balances.

​
feature_id
string

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.

​
cache_read_tokens
integer

Number of cached input tokens read.

Required range: 0 <= x <= 9007199254740991
​
cache_write_tokens
integer

Number of input tokens written to the cache.

Required range: 0 <= x <= 9007199254740991
​
audio_input_tokens
integer

Number of audio input tokens consumed.

Required range: 0 <= x <= 9007199254740991
​
audio_output_tokens
integer

Number of audio output tokens generated.

Required range: 0 <= x <= 9007199254740991
​
reasoning_tokens
integer

Number of reasoning tokens generated.

Required range: 0 <= x <= 9007199254740991
​
properties
object

Additional properties to attach to this usage event.

Response

OK

​
customer_id
string
required

The ID of the customer whose usage was tracked.

​
value
number
required

The amount of usage that was recorded.

​
balance
object
required

The updated balance for the tracked feature. Null if tracking by event_name that affects multiple features.

Example:
{
  "feature_id": "messages",
  "granted": 100,
  "remaining": 72,
  "usage": 28,
  "unlimited": false,
  "overage_allowed": false,
  "max_purchase": null,
  "next_reset_at": 1773851121437,
  "breakdown": [
    {
      "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
      "plan_id": "pro_plan",
      "included_grant": 100,
      "prepaid_grant": 0,
      "remaining": 72,
      "usage": 28,
      "unlimited": false,
      "reset": {
        "interval": "month",
        "resets_at": 1773851121437
      },
      "price": null,
      "expires_at": null
    }
  ]
}
​
entity_id
string

The ID of the entity, if entity-scoped tracking was performed.

​
event_name
string

The event name that was tracked, if event_name was used instead of feature_id.

​
balances
object

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.

​
deductions
object[]

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.