---
title: "POST /v1/balances.track_tokens"
method: POST
path: "/v1/balances.track_tokens"
---

# POST /v1/balances.track_tokens

`POST /v1/balances.track_tokens`

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.

## Headers

- `x-api-version` string, required

## Request body

- object
  - `customer_id` string, required — The ID of the customer.
  - `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.
  - `model_id` string, required — 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.
  - `input_tokens` integer, required — Number of non-cached text input tokens consumed. Exclusive of cache and audio token pools.
  - `output_tokens` integer, required — Number of text output tokens consumed. Exclusive of the reasoning and audio output pools.
  - `cache_read_tokens` integer — Number of cached input tokens read.
  - `cache_write_tokens` integer — Number of input tokens written to the cache.
  - `audio_input_tokens` integer — Number of audio input tokens consumed.
  - `audio_output_tokens` integer — Number of audio output tokens generated.
  - `reasoning_tokens` integer — Number of reasoning tokens generated.
  - `properties` object — Additional properties to attach to this usage event.
  - `timestamp` integer — Unix timestamp in milliseconds to use for the usage event. Defaults to the current time.
  - `overage_behavior` 'cap' | 'overflow' — How 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.
  - `async` boolean — If true, enqueue the event for asynchronous processing and return 204 immediately. The response will not include balance information.

## Response `200`

OK

- object
  - `customer_id` string, required — The ID of the customer whose usage was tracked.
  - `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.
  - `value` number, required — The amount of usage that was recorded.
  - `balance` Balance, required
    - `feature_id` string, required — The feature ID this balance is for.
    - `feature` object — The full feature object if expanded.
      - `id` string, required — The unique identifier for this feature, used in /check and /track calls.
      - `name` string, required — Human-readable name displayed in the dashboard and billing UI.
      - `type` 'boolean' | 'metered' | 'credit_system' | 'ai_credit_system', required — Feature type: 'boolean' for on/off access, 'metered' for usage-tracked features, 'credit_system' for unified credit pools, 'ai_credit_system' for model-based token pricing.
      - `consumable` boolean, required — For metered features: true if usage resets periodically (API calls, credits), false if allocated persistently (seats, storage).
      - `event_names` string[] — Event names that trigger this feature's balance. Allows multiple features to respond to a single event.
      - `credit_schema` object[] — For credit_system features: maps metered features to their credit costs.
        - `metered_feature_id` string, required — ID of the metered feature that draws from this credit system.
        - `credit_cost` number, required — Credits consumed per unit of the metered feature.
      - `model_markups` object, nullable — Per-model markup overrides for AI credit systems.
      - `default_markup` number — Default percentage markup for AI credit systems. Use -100 to make usage free.
      - `provider_markups` object, nullable — Per-provider default markup percentages for AI credit systems.
      - `display` object — Display names for the feature in billing UI and customer-facing components.
        - `singular` string, nullable — Singular form for UI display (e.g., 'API call', 'seat').
        - `plural` string, nullable — Plural form for UI display (e.g., 'API calls', 'seats').
      - `archived` boolean, required — Whether the feature is archived and hidden from the dashboard.
    - `granted` number, required — Total balance granted (included + prepaid).
    - `remaining` number, required — Remaining balance available for use.
    - `usage` number, required — Total usage consumed in the current period.
    - `unlimited` boolean, required — Whether this feature has unlimited usage.
    - `overage_allowed` boolean, required — Whether usage beyond the granted balance is allowed (with overage charges).
    - `max_purchase` number, nullable, required — Maximum quantity that can be purchased as a top-up, or null for unlimited.
    - `next_reset_at` number, nullable, required — Timestamp when the balance will reset, or null for no reset.
    - `breakdown` object[] — Detailed breakdown of balance sources when stacking multiple plans or grants.
      - `id` string — The unique identifier for this balance breakdown.
      - `plan_id` string, nullable, required — The plan ID this balance originates from, or null for standalone balances.
      - `included_grant` number, required — Amount granted from the plan's included usage.
      - `prepaid_grant` number, required — Amount granted from prepaid purchases or top-ups.
      - `remaining` number, required — Remaining balance available for use.
      - `usage` number, required — Amount consumed in the current period.
      - `unlimited` boolean, required — Whether this balance has unlimited usage.
      - `reset` object, nullable, required — Reset configuration for this balance, or null if no reset.
        - `interval` union, required — The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
          - 'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
          - 'multiple'
        - `interval_count` number — Number of intervals between resets (eg. 2 for bi-monthly).
        - `resets_at` number, nullable, required — Timestamp when the balance will next reset.
      - `price` object, nullable, required — Pricing configuration if this balance has usage-based pricing.
        - `amount` number — The per-unit price amount.
        - `tiers` object[] — Tiered pricing configuration if applicable.
          - `to` union, required
            - number
            - 'inf'
          - `amount` number, required
          - `flat_amount` number
        - `tier_behavior` 'graduated' | 'volume' — How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
        - `billing_units` number, required — The number of units per billing increment (eg. $9 / 250 units).
        - `billing_method` 'prepaid' | 'usage_based', required — Whether usage is prepaid or billed pay-per-use.
        - `max_purchase` number, nullable, required — Maximum quantity that can be purchased, or null for unlimited.
      - `expires_at` number, nullable, required — Timestamp when this balance expires, or null for no expiration.
    - `rollovers` object[] — Rollover balances carried over from previous periods.
      - `balance` number, required — Amount of balance rolled over from a previous period.
      - `expires_at` number, required — Timestamp when the rollover balance expires.
  - `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.
    - `balance_id` string, required — ID of the underlying balance row that was deducted from (customer_entitlement or rollover).
    - `feature_id` string, required — The feature this balance belongs to.
    - `plan_id` string, nullable, required — ID of the plan/product this balance belongs to. Null when the balance can't be attributed to a single plan (e.g. it spans multiple).
    - `reset` object, nullable, required — Reset configuration for the balance this deduction came from, or null if the balance doesn't reset.
      - `interval` union, required — The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
        - 'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'
        - 'multiple'
      - `interval_count` number — Number of intervals between resets (eg. 2 for bi-monthly).
      - `resets_at` number, nullable, required — Timestamp when the balance will next reset.
    - `value` number, required — Amount deducted from this balance. Positive when usage was consumed, negative when credit was restored (e.g. a refund via negative track value).

## Other responses

- `202` — Accepted. Autumn is experiencing degraded service from a downstream provider, so the token usage event was accepted for replay and will be tracked as soon as the service is restored.

---

[API](https://skmtc.net/useautumn/apis/autumn-api.md) · [All operations](https://skmtc.net/useautumn/apis/autumn-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/useautumn/autumn-api/versions/29536933c0dc/schema)