tokens-usage
The invoice you did not budget for
A long conversation with tool calls quietly doubles your input tokens. You only notice when the monthly bill arrives.
Count tokens before you send the request
Know your input size and estimated cost before hitting the API. Plan context windows, avoid surprise bills, and persist accurate token counts to your database.
npm install tokens-usage
countTokens.ts
The problem
Token counts should not be a surprise
Every LLM request carries a cost and a context limit. Without accurate input counts upfront, you are flying blind on both.
The prompt that does not fit
You trim messages blindly because you are guessing at the context limit. Important history gets dropped at the worst moment.
Estimates that lie to you
Character counts and rough heuristics miss provider-specific formatting. Your dashboards show numbers that do not match reality.
The solution
Accurate counts before every request
tokens-usage gives you provider-accurate input counts, fallback strategies, and cost estimates in a single call — before you hit send.
One API, three providers
Count tokens for OpenAI, Anthropic, and Google with the same function call. Pass native payloads or plain text — the shape is auto-detected.
Native AI SDK support
Accept ModelMessage and UIMessage arrays directly. Strict model validation per provider when using AI SDK formats.
Endpoint with local fallback
Mode auto tries the provider endpoint first, then falls back to tiktoken, Anthropic tokenizer, or heuristics — no network required.
USD cost estimates
Get an estimated input cost when the model is in the pricing table. Know the dollar impact before you send.
Control tool token counts
countAssistantTools defaults to true. Set it to false to exclude function_call, tool_use, and functionResponse blocks from the count.
How it works
Three steps to predictable token usage
- 01
Install the package
Add tokens-usage to your project. Install ai as well if you pass UIMessage arrays.
npm install tokens-usage - 02
Pass your content
Send a string, native provider payload, or AI SDK messages. Content shape is inferred automatically — no inputMode field needed.
content: [{ role: "user", content: "Hello" }] - 03
Get tokens, method, and price
Receive an accurate count, the strategy used, and a USD estimate when pricing data exists.
{ tokens, estimated, method, price }
Usage
One function, full visibility
Call countTokens before sending a request or persisting a provider response. The result tells you exactly what was counted and how.
import { countTokens } from "tokens-usage";
const result = await countTokens({
provider: "openai",
model: "gpt-4o",
content: [{ role: "user", content: "Hello" }],
apiKey: process.env.OPENAI_API_KEY,
});
console.log(result.tokens); // 9
console.log(result.method); // "provider_endpoint"
console.log(result.price); // { usd: 0.00002 }Providers
Built for the providers you already use
Native payload formats for each provider, plus AI SDK ModelMessage and UIMessage support. AI SDK is a message format — not a provider.
OpenAI 
Anthropic 
Google OpenAI gpt-4o, gpt-5.5, ResponseInput
Anthropic claude-sonnet-4-6, MessageParam[]
Google gemini-3.5-flash, Content[]
Environment variables
| Provider | Variable |
|---|---|
| OpenAI | OPENAI_API_KEY |
| Anthropic | ANTHROPIC_API_KEY |
GOOGLE_GENERATIVE_AI_API_KEY |
FAQ
Common questions
What is the difference between endpoint and local mode?
Endpoint mode calls the provider official counting API for the most accurate result. Local mode uses tiktoken for OpenAI, the Anthropic tokenizer, or a chars/4 heuristic for Google — no network required. Auto tries endpoint first and falls back to local on recoverable errors.
Do I need to install AI SDK?
Only if you pass UIMessage arrays as content. UIMessage is converted internally with AI SDK convertToModelMessages, which requires the ai peer dependency. ModelMessage arrays and native provider payloads do not require it.
Does tokens-usage count output tokens?
No. tokens-usage counts input tokens only — the prompt or messages you send before the model responds. Output token tracking is out of scope for v1.
Why is price sometimes null?
The price field returns a USD estimate only when the model exists in the tokens-usage pricing table. If the model is unknown or not yet catalogued, price is null even though tokens and method are still returned.
Can I pass my API key directly?
Yes. Pass apiKey in the options object, or set the provider environment variable: OPENAI_API_KEY, ANTHROPIC_API_KEY, or GOOGLE_GENERATIVE_AI_API_KEY (also GEMINI_API_KEY or GOOGLE_API_KEY for Google).
What license does tokens-usage use?
tokens-usage is source-available under a custom license. See LICENSE.md in the repository for full terms before using in production.
Start counting before you send
Add tokens-usage to your stack today. Source-available license — see LICENSE.md for terms.
npm install tokens-usage