tokenlens 0.2.0

Track and optimize your LLM spend — find duplicates, wasted tokens, and cost savings.

TokenLens Python SDK

Track and optimize your LLM spend. Find duplicate prompts, wasted tokens, and cost savings — automatically.

Install

pip install tokenlens

Quick Start (2 lines)

import tokenlens
tokenlens.init(api_key="tl_...")  # Get your key at tokenlens.co/app → Account

# All OpenAI and Anthropic calls are now tracked automatically.
# No other code changes needed.

How It Works

The SDK patches the OpenAI and Anthropic Python clients to capture usage metadata (model, token counts, prompt hashes) after every completion call. Events are batched in the background and sent to your TokenLens dashboard every 30 seconds.

What's captured: model name, token counts, prompt text (for duplicate detection), cost, timestamps.

What's NOT captured: API keys, response content beyond the first 2KB, any data outside of LLM calls.

With OpenAI

import tokenlens
tokenlens.init(api_key="tl_...")

from openai import OpenAI
client = OpenAI()

# This call is automatically tracked
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Summarize this article"}]
)

With Anthropic

import tokenlens
tokenlens.init(api_key="tl_...")

import anthropic
client = anthropic.Anthropic()

# This call is automatically tracked
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain quantum computing"}]
)

With LiteLLM

import litellm
from tokenlens.litellm_callback import TokenLensCallback

litellm.callbacks = [TokenLensCallback(api_key="tl_...")]

# Every litellm.completion() call is now tracked
response = litellm.completion(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)

LiteLLM Proxy (config.yaml)

litellm_settings:
  callbacks:
    - tokenlens

environment_variables:
  TOKENLENS_API_KEY: "tl_..."

Manual Tracking

For custom LLM clients or pre-computed metrics:

import tokenlens
tokenlens.init(api_key="tl_...")

tokenlens.track(
    model="gpt-4o",
    prompt="Summarize the quarterly report",
    tokens_in=150,
    tokens_out=500,
    cost=0.0035,
    caller_tag="report-service",
)

Environment Variables

Variable	Description
TOKENLENS_API_KEY	Your API key (alternative to passing api_key=)
TOKENLENS_API_BASE	Custom API endpoint (default: https://tokenlens.co)

Configuration

tokenlens.init(
    api_key="tl_...",
    auto_patch=True,       # Patch OpenAI/Anthropic automatically (default: True)
    batch_size=50,         # Events per batch (default: 50)
    flush_interval=30,     # Seconds between flushes (default: 30)
    debug=False,           # Enable debug logging (default: False)
)

SDK Stats

print(tokenlens.stats())
# {'queued': 3, 'total_sent': 147, 'total_errors': 0}

Graceful Shutdown

Events are flushed automatically on process exit. For explicit control:

tokenlens.flush()     # Send all pending events now
tokenlens.shutdown()  # Flush and stop background thread

Privacy

• Prompt text is sent for duplicate detection (hashed on our servers, never stored in plain text)
• Completion text is capped at 2KB and used only for quality analysis
• No API keys, secrets, or credentials are ever captured
• All data is encrypted in transit (HTTPS/TLS)
• Data is scoped to your team — never shared across accounts

Requirements

• Python 3.8+
• No required dependencies (works standalone)
• Optional: openai>=1.0, anthropic>=0.20, litellm>=1.0

Links

• TokenLens Dashboard
• Documentation
• Report Issues

License

MIT