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,
});

from autumn_sdk import Autumn

autumn = Autumn(secret_key="am_sk_test...")

res = autumn.track_tokens(
    customer_id="cus_123",
    model_id="anthropic/claude-sonnet-4-20250514",
    input_tokens=1000,
    output_tokens=500,
    feature_id="ai_credits",
)

curl --request POST \
  --url https://api.useautumn.com/v1/balances.track_tokens \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '
{
  "customer_id": "cus_123",
  "feature_id": "ai_credits",
  "model_id": "anthropic/claude-sonnet-4-20250514",
  "input_tokens": 1000,
  "output_tokens": 500
}
'

{
  "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
    }
  ]
}

POST

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,
});

from autumn_sdk import Autumn

autumn = Autumn(secret_key="am_sk_test...")

res = autumn.track_tokens(
    customer_id="cus_123",
    model_id="anthropic/claude-sonnet-4-20250514",
    input_tokens=1000,
    output_tokens=500,
    feature_id="ai_credits",
)

curl --request POST \
  --url https://api.useautumn.com/v1/balances.track_tokens \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '
{
  "customer_id": "cus_123",
  "feature_id": "ai_credits",
  "model_id": "anthropic/claude-sonnet-4-20250514",
  "input_tokens": 1000,
  "output_tokens": 500
}
'

{
  "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
    }
  ]
}

Body Parameters

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
    }
  ]
}

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.6.0

required

Body

application/json

customer_id

string

required

The ID of the customer.

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.

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.

Show child attributes

timestamp

integer

Unix timestamp in milliseconds to use for the usage event. Defaults to the current time.

Required range: 0 < x <= 9007199254740991

overage_behavior

enum<string>

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.

Available options:

cap,

overflow

async

boolean

Defaults to true: the event is queued and the response is a 202 with balance: null. Set to false to apply the usage before responding with a 200 and the updated balance.

Response

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 | null

required

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

Show child attributes

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.

Show child attributes

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.

Show child attributes

Billing

Balances

Customers

Invoices

Authorization

Analytics

Logs

Entities

Accounts

Plans

Features

Rewards & Referrals

Webhooks

Webhook Events

Platform (Beta)

Body Parameters

Response

Authorizations

Headers

Body

Response