SDK

trackedCall()

Wraps a standard (non-streaming) LLM call and logs cost data to your dashboard. Supports Anthropic, OpenAI, Google Gemini, and any OpenAI-compatible provider (DeepSeek, xAI, Perplexity). Returns the identical response as the underlying call.

Usage

import { trackedCall } from '@llmcosttracker/sdk'const response = await trackedCall({client: anthropic, group: 'summarize', userId: session.userId, tier: session.plan, apiKey: 'lct_live_your_key_here', params: {model: 'claude-sonnet-4-6', messages, max_tokens: 1024,},})

Parameters

clientAnthropic | OpenAI | GoogleGenerativeAIrequiredYour initialized client instance. Pass an Anthropic client, any OpenAI-compatible client (OpenAI, DeepSeek, xAI, Perplexity), or a Google GenerativeAI client — the SDK detects the provider automatically.
paramsobjectrequiredThe exact params you would pass to the underlying create() call.
apiKeystringrequiredYour LLM Cost Tracker project API key. Found in Settings.
groupstringoptionalTag for this call — e.g. "search", "summarize", "backend-team". Used to attribute spend in the dashboard and against spend targets.
userIdstringoptionalYour app's user identifier. Used for per-user cost attribution and budget enforcement.
tierstringoptionalYour pricing tier for this user — e.g. "free", "pro", "enterprise". Used for tier template enforcement. Must match the tier label configured in your Enforcement dashboard exactly.
promptVersionstringoptionalVersion label for your prompt — e.g. a git SHA or "v2.1". Used for before/after cost comparisons in the dashboard.
budgetBudgetConfigoptionalPer-call budget configuration. Takes precedence over any dashboard-configured tier template. See Budget enforcement.
onBudgetWarning(result: BudgetCheckResult) => voidoptionalCallback fired when spend reaches the alert threshold or when action is "warn". Receives the current spend, limit, and budget config.
endpointstringoptionalCustom endpoint URL. Only needed for self-hosted installs.

Returns

The exact response from the underlying LLM call — identical to calling the provider's API directly.

Error handling

If logging fails for any reason, the error is caught silently. The function always returns the LLM response — a logging failure will never throw or affect your application.

The one exception is budget enforcement. If a budget is configured with action: "block" and the user has reached their limit, trackedCall() throws LLMBudgetExceededError before making the underlying API call. Catch it explicitly:

import { trackedCall, LLMBudgetExceededError } from '@llmcosttracker/sdk'try {const response = await trackedCall({ client, params, apiKey, userId, tier })return response} catch (err) {if (err instanceof LLMBudgetExceededError) {// return a graceful response to your userreturn { error: 'limit_reached', message: 'Monthly AI usage limit reached.' }}throw err}

See Handling blocks for full details including reset date calculation and the warning callback.

Next: trackedStream() →