Tokenlens Overview

⚠️ Experimental Docs:
These docs cover Tokenlens v2. For early access, install the alpha:
npm i tokenlens@alpha

Tokenlens provides provider-aware model metadata and usage utilities for AI applications. It resolves canonical model ids across multiple data sources, normalizes usage payloads, and estimates token costs/context limits with a consistent TypeScript API.

Why Tokenlens?

Consistent metadata: Works with dynamic catalogs such as OpenRouter, models.dev, and Vercel AI Gateway, plus local fixture data.
Usage normalization: Understands common SDK payloads (OpenAI, Anthropic, Vercel AI SDK LanguageModelV2, etc.).
Cost and context: Quickly estimate USD costs, check context windows, and inform compaction strategies.
Typed surface: Ships DTOs for the metadata it returns (ModelDetails, TokenCosts, etc.).

Core Concepts

Tokenlens instance

A Tokenlens instance encapsulates:

The catalog to load ("auto" – alias for OpenRouter, "openrouter", "models.dev", "vercel", or a custom SourceProviders object).
Cache behaviour (ttlMs, cache, and cacheKey) that controls how long a loaded catalog is reused.
Optional wiring such as a custom cache adapter suited to your runtime.

The instance exposes helper methods that all operate on the same cached catalog:

getModelData({ modelId, provider? })
computeCostUSD({ modelId, provider?, usage })
getContextLimits({ modelId, provider? })
getContextHealth({ modelId, provider?, usage })
countTokens({ modelId, data }) and estimateCostUSD({ modelId, data, provider? })

Catalogs

Tokenlens ships with gateway identifiers that point at hosted catalogs:

"auto" – alias for the OpenRouter gateway (default when no catalog is provided).
"openrouter" – live OpenRouter API.
"models.dev" – curated dataset derived from models.dev.
"vercel" – Vercel AI Gateway models endpoint.

Pass one of these identifiers via catalog to switch gateways, or supply your own SourceProviders object to run entirely on local fixture data (useful for tests and offline tooling).

Caching

Tokenlens caches provider metadata via an in-memory adapter (MemoryCache) by default. Features:

TTL defaults to 24h (ttlMs), with ±5% jitter to avoid synchronized reloads.
cache option accepts custom adapters ({ get, set, delete }) to back the cache with Redis or other stores.
On fetch errors, Tokenlens falls back to the last cached entry if available.

Standalone helpers

The root module also exports computeCostUSD, getModelData, getContextLimits, getContextHealth, countTokens, and estimateCostUSD. The first call to any helper lazily creates a shared Tokenlens instance with default options (catalog: "auto"—the OpenRouter gateway—and an in-memory cache). Use the gateway option (for example, { gateway: "models.dev" }) or instantiate via createTokenlens() when you need a different catalog.

When you require custom configuration (specific gateway, custom cache, fixture catalogs), instantiate an explicit Tokenlens client via createTokenlens and reuse it within your application.

Architecture Diagram

┌─────────────┐     ┌────────────────────┐
│  Tokenlens  │────▶│  Catalog Gateway  │
└─────┬───────┘     │   (auto, ...)     │
      │              └────────────────────┘
      │ providers
      ▼
┌─────────────────────┐
│   Provider Cache    │
└────────┬────────────┘
         │
         ▼
 ┌────────────────────────────┐
 │  Helpers / Methods         │
 │  • getModelData            │
 │  • computeCostUSD          │
 │  • getContextLimits        │
 │  • getContextHealth        │
 └────────────────────────────┘

When to use Tokenlens

You need reliable cost estimates across multiple providers.
Your application must determine if a usage payload exceeds model context limits.
You integrate with SDKs that emit usage in differing shapes (Vercel AI SDK, OpenAI, Anthropic, etc.).
You want to merge live provider data with in-app fixture data while keeping a single lookup API.