SDK

Configuration

LLM Cost Tracker requires minimal configuration. The only required value is your project API key.

API key

Your API key is found in your LLM Cost Tracker dashboard under Settings. It looks like this:

lct_live_a1b2c3d4e5f6...

Pass it as the apiKey parameter on every tracked call. We recommend storing it as an environment variable:

# .env.localLLMCOSTTRACKER_API_KEY=lct_live_your_key_here
const response = await trackedCall({client: anthropic, apiKey: process.env.LLMCOSTTRACKER_API_KEY, group: 'search', params,})

Group tags

The group parameter is free-form text — use any string that makes sense for your product. It's how spend gets attributed in the dashboard and in spend targets.

  • Feature names: 'search', 'summarize', 'chat', 'classify'
  • Team or workflow names: 'backend-team', 'onboarding-flow'
  • Client or campaign names: 'client-acme', 'q3-campaign'
  • Avoid: 'llm_call', 'test', 'misc' — too generic to be useful

Use consistent names across your codebase so the dashboard grouping is meaningful. The same string you pass as group is what you'll set spend targets against.

User and tier tagging

Pass userId and tier on every call to unlock per-user attribution and budget enforcement.

await trackedCall({client: anthropic, apiKey: process.env.LLMCOSTTRACKER_API_KEY, group: 'search', userId: session.userId,   // your app's user identifiertier: session.plan,       // 'free' | 'pro' | 'enterprise'params,})
  • userId — enables the By user dashboard view and per-user spend tracking. Required for per-user budget enforcement.
  • tier — enables tier template enforcement. Must match the tier label configured in your Enforcement dashboard exactly. Case-sensitive.

Both fields are optional at the SDK level — calls without them are still tracked and attributed to the project. But without userId you lose per-user visibility, and without tier tier template enforcement won't fire.

Budget enforcement

Once you're passing userId and tier, you can configure spend limits in the dashboard and have them enforced automatically. No additional SDK config is required for warn mode. For block mode, wrap your calls in a try/catch:

import { trackedCall, LLMBudgetExceededError } from '@llmcosttracker/sdk'try {await trackedCall({ client, params, apiKey, userId, tier })} catch (err) {if (err instanceof LLMBudgetExceededError) {// return a graceful response to your user}throw err}

See Budget enforcement for full configuration details.

Custom endpoint

If you are self-hosting LLM Cost Tracker, point the SDK at your own instance:

const response = await trackedCall({client: anthropic, apiKey: process.env.LLMCOSTTRACKER_API_KEY, endpoint: 'https://your-instance.com/api/events', group: 'search', params,})

Next: Dashboard guide →