---
title: "Track Token Usage"
openapi: "openapi POST /v1/balances.track_tokens"
---

import { DynamicParamField } from "/components/dynamic-param-field.jsx";
import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
import { DynamicResponseField } from "/components/dynamic-response-field.jsx";

<Note>
  Track AI token usage against a customer's AI credit system balance. Converts token counts to a dollar cost using [Models.dev](https://models.dev) pricing and your configured markup, then deducts from the customer's credit balance.
</Note>

The `model_id` must use `provider/model` format, matching the provider and model keys from [Models.dev](https://models.dev). For providers with nested model paths (like OpenRouter), include the full path: `openrouter/anthropic/claude-opus-4.6`.

### Common Use Cases

<CodeGroup>

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

```typescript OpenAI
await autumn.balances.trackTokens({
  customerId: "cus_123",
  modelId: "openai/gpt-4o",
  inputTokens: 500,
  outputTokens: 200,
  properties: {
    conversation_id: "conv_abc123",
    prompt_type: "summarization"
  }
});
```

```typescript OpenRouter (nested path)
await autumn.balances.trackTokens({
  customerId: "cus_123",
  modelId: "openrouter/anthropic/claude-opus-4-6",
  inputTokens: 2000,
  outputTokens: 1000
});
```

```typescript With explicit feature
await autumn.balances.trackTokens({
  customerId: "cus_123",
  featureId: "ai_credits",
  modelId: "anthropic/claude-haiku-4-5",
  inputTokens: 2000,
  outputTokens: 1000
});
```

</CodeGroup>