Guides

Quickstart

Five steps from a bare provider client to your first attributed usage event. Every snippet below is real code copied from the SDK sources, not invented.

1. Install

shell

npm install @tokenmeter/sdk

Use the Token Meter package and module names shown below.

2. Initialize

Pass your tl_live_… ingest key once, at process start.

TypeScript

import { TokenMeterClient } from "@tokenmeter/sdk";

const tl = new TokenMeterClient({ apiKey: process.env.TOKEN_METER_KEY! });

The SDK is public and installable by anyone. It does nothing without a valid key. Rate limits, tier caps, and soft-lock are all enforced server-side at the ingest door, not in the SDK.

3. Wrap your client

Wrap the provider client you already construct. Detection is structural: Python duck-types the client shape, and the TypeScript wrapper functions patch the specific methods each provider exposes, so it works whichever version of the provider SDK you already have installed.

wrap.ts

import OpenAI from "openai";
import { wrapOpenAI } from "@tokenmeter/sdk";

const openai = wrapOpenAI(new OpenAI(), tl);

In Python, wrap() is idempotent: wrapping an already-wrapped client or method is a no-op. Anthropic, Gemini, Bedrock, and Azure OpenAI all follow the same shape; see Providers.

4. Send a first event

Open an action() scope around the call you want attributed, then call the wrapped client exactly as before.

first-event.ts

import { action } from "@tokenmeter/sdk";

await action("generate-report", { customerRef: "acme", feature: "reports" }, async () => {
  await openai.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: "hi" }],
  });
  // usage for this call is captured automatically, tagged with
  // customer_ref=acme, feature=reports, and a shared trace_id.
});

5. See it on the dashboard

Events flush on their own, every 2 seconds or 500 events (whichever comes first), so there's nothing else to call for a normal long-running process. Open your Token Meter dashboard and the call you just made should show up under Actions within a few seconds. If it doesn't, run tokenmeter.diagnose() (Python). It pings the Ingest API synchronously and prints exactly why a key is invalid, revoked, or unreachable, instead of leaving you staring at a silent dashboard. See the reference.