Registry / llm-agents / tokencost

tokencost

JSON →
library0.1.26pypypi✓ verified 23d ago

tokencost is a Python library that provides client-side token counting and USD cost estimation for over 400 Large Language Models (LLMs) from providers like OpenAI, Anthropic, Google, and AWS Bedrock. It helps AI agents and LLM applications accurately track and manage API expenses by offering up-to-date pricing and model-specific tokenization, released frequently to reflect changing LLM provider costs.

pip install tokencost
INSTALL
IMPORT
SIG · TOKENCOST
T
tokencost
llm-agentspythonv0.1.26
Install
8.9s avg
Import
3063ms
Disk
68MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.1.26 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 3.190s · 67.4MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 8.9s · import 2.936s · 69MB
68MB installed
● package 68MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

calculate_prompt_cost
from tokencost import calculate_prompt_cost
calculate_completion_cost
from tokencost import calculate_completion_cost

This quickstart demonstrates how to calculate the estimated token cost for both a prompt and its completion using `tokencost`. It includes an optional interaction with the OpenAI API for a realistic example, which requires the `OPENAI_API_KEY` environment variable to be set. The library automatically handles different tokenization methods for various LLM providers.

import os from openai import OpenAI from tokencost import calculate_prompt_cost, calculate_completion_cost # Ensure OPENAI_API_KEY is set in your environment variables openai_api_key = os.environ.get('OPENAI_API_KEY', 'YOUR_OPENAI_API_KEY') if not openai_api_key or openai_api_key == 'YOUR_OPENAI_API_KEY': print("Warning: OPENAI_API_KEY environment variable not set. Using dummy key.") # This allows the example to run without an actual API call, but cost calculation still works. # For actual API calls, replace with a valid key or set the env var. client = OpenAI(api_key=openai_api_key) model = "gpt-3.5-turbo" prompt_messages = [{ "role": "user", "content": "Say this is a test"}] # Simulate an OpenAI API call (or make a real one if API key is valid) try: chat_completion = client.chat.completions.create( messages=prompt_messages, model=model ) completion_content = chat_completion.choices[0].message.content print(f"API Completion: {completion_content}") except Exception as e: print(f"Could not make actual OpenAI API call (continuing with dummy completion for cost calculation): {e}") completion_content = "This is a test." # Calculate costs prompt_cost = calculate_prompt_cost(prompt_messages, model) completion_cost = calculate_completion_cost(completion_content, model) total_cost = prompt_cost + completion_cost print(f"Prompt Cost: ${prompt_cost:.6f}") print(f"Completion Cost: ${completion_cost:.6f}") print(f"Total Estimated Cost: ${total_cost:.6f}")
Debug
Known issues
gotchaLLM providers frequently update model pricing and introduce new models. To ensure accurate cost estimations, it is crucial to keep the `tokencost` library updated to its latest version.
fix
Regularly update the library: `pip install --upgrade tokencost`.
affects: All versions
gotchaDifferent LLM providers (e.g., OpenAI, Anthropic) use distinct tokenization methods. Manual token counting or cost estimation can be inaccurate due to these variations (e.g., Tiktoken for OpenAI, Anthropic's beta API for Claude 3.5+). `tokencost` abstracts this complexity, using the appropriate tokenizer for each model.
fix
Always use `tokencost` for reliable, model-specific token counting and cost estimation instead of attempting manual calculations or generic tokenizers.
affects: All versions
gotchaSome advanced LLMs generate 'reasoning tokens' (internal thought processes) that are billed at the more expensive output token rate but are not visible in the final API response. This can lead to higher-than-expected costs for a given visible output. `tokencost` helps in understanding the total cost incurred by such models.
fix
Monitor total costs reported by `tokencost` and consider using more cost-efficient models or prompt engineering strategies to reduce internal reasoning if costs are a concern.
affects: Models with internal reasoning capabilities (e.g., GPT-4, Claude Opus)
breakingPast versions (e.g., 0.1.20) had fixes for incorrect token and cost calculations for certain OpenAI 'o' series models and issues with lazy loading of `update_token_costs`. While addressed, this highlights the dynamic nature of LLM pricing and tokenization.
fix
Ensure you are on `tokencost` version 0.1.20 or newer to benefit from these specific fixes. Always keep the library updated to receive the latest pricing and tokenization logic corrections.
affects: <=0.1.19
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'tokencost'
The tokencost library has not been installed in your current Python environment.
fix
pip install tokencost
KeyError: 'invalid_model_name'
The provided model name is either misspelled or not supported by the tokencost library.
fix
Consult the tokencost documentation or available model list to use a correct and valid model name (e.g., 'gpt-4', 'claude-3-opus-20240229').
TypeError: expected string or bytes-like object, got list
The 'text' argument passed to tokencost.count_tokens or tokencost.estimate_cost is not a string.
fix
Ensure the 'text' argument is a single string; if you have multiple texts, process them individually or concatenate them into a single string.
Upgrade
Version history
0.1.26latest on PyPI · released Aug 13, 2025
Audit
Dependencies
openaioptionalUsed in common quickstart examples for actual API calls, though not a direct installation dependency of tokencost itself.
Agent activity
40 hits · last 30 days
node
36
Amazon
1
OpenAI (training)
1
Resources
tokencost — pip install tokencost · libregistry