Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB

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.

post/v1/balances.track_tokens

Headers

x-api-versionstring required

Request body

customer_idstring required

The ID of the customer.

entity_idstring

The ID of the entity for entity-scoped balances.

feature_idstring

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_idstring 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_tokensinteger required

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

output_tokensinteger required

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

cache_read_tokensinteger

Number of cached input tokens read.

cache_write_tokensinteger

Number of input tokens written to the cache.

audio_input_tokensinteger

Number of audio input tokens consumed.

audio_output_tokensinteger

Number of audio output tokens generated.

reasoning_tokensinteger

Number of reasoning tokens generated.

propertiesobject

Additional properties to attach to this usage event.

timestampinteger

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.

asyncboolean

If true, enqueue the event for asynchronous processing and return 204 immediately. The response will not include balance information.

Example request

{
  "customer_id": "cus_123",
  "feature_id": "ai_credits",
  "model_id": "anthropic/claude-sonnet-4-20250514",
  "input_tokens": 1000,
  "output_tokens": 500
}

Response

OK

customer_idstring required

The ID of the customer whose usage was tracked.

entity_idstring

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

event_namestring

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

valuenumber required

The amount of usage that was recorded.

balancesobject

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.

Example response

{
  "customer_id": "cus_123",
  "value": 0.006,
  "balance": {
    "feature_id": "ai_credits",
    "granted": 10,
    "remaining": 9.994,
    "usage": 0.006,
    "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
      }
    ]
  },
  "deductions": [
    {
      "balance_id": "cus_ent_3DdSDoyFmoA9Neecl2a2Gc507X2",
      "feature_id": "ai_credits",
      "plan_id": "pro",
      "reset": {
        "interval": "month",
        "resets_at": 1781288736881
      },
      "value": 0.006
    }
  ]
}