llmtrack-sdk (Python)

LLMtrack records server-side LLM token usage, cost, and request context so teams can understand AI usage in one dashboard.

[!WARNING] Server-side only. Never put an LLMtrack key in browser, mobile, desktop-client, or other public code. Load it from a server-side environment variable only.

The PyPI distribution is named llmtrack-sdk, while Python imports use llmtrack_sdk: distribution names can contain hyphens, but import identifiers cannot, and the distinct name also avoids the unrelated llmtrack distribution.

Install

pip install llmtrack-sdk

Quickstart

Create an ingestion key in LLMtrack, save it at ~/.config/llmtrack/api-key, and run:

export LLMTRACK_API_KEY="$(cat ~/.config/llmtrack/api-key)"

import os
from llmtrack_sdk import LLMtrack
tracker = LLMtrack(api_key=os.environ["LLMTRACK_API_KEY"])
tracker.track(provider="openai", model="gpt-5.6-sol", prompt_tokens=241,
              completion_tokens=86, reasoning_tokens=32, feature="support-chat")

Provider examples

Both examples call track() immediately after the provider completion and read counts from the official response objects.

OpenAI

import os
from openai import OpenAI
from llmtrack_sdk import LLMtrack
openai, tracker = OpenAI(), LLMtrack(api_key=os.environ["LLMTRACK_API_KEY"])
response = openai.chat.completions.create(model="gpt-5.6-sol", messages=[{"role": "user", "content": "Explain why the sky is blue in two sentences."}])
usage = response.usage
tracker.track(provider="openai", model=response.model, prompt_tokens=usage.prompt_tokens, completion_tokens=usage.completion_tokens,
              reasoning_tokens=usage.completion_tokens_details.reasoning_tokens if usage.completion_tokens_details else 0, feature="science-explainer")

Anthropic

Anthropic includes thinking tokens in output_tokens rather than exposing a separate reasoning-token count, so do not duplicate them in reasoning_tokens.

import os
from anthropic import Anthropic
from llmtrack_sdk import LLMtrack
anthropic, tracker = Anthropic(), LLMtrack(api_key=os.environ["LLMTRACK_API_KEY"])
response = anthropic.messages.create(model="claude-opus-5", max_tokens=1024, messages=[{"role": "user", "content": "Summarize the benefits of typed APIs."}])
tracker.track(provider="anthropic", model=response.model, prompt_tokens=response.usage.input_tokens,
              completion_tokens=response.usage.output_tokens, feature="document-summary")

Fire-and-forget and awaited usage

result = await tracker.track_sync(provider="openai", model="gpt-5.6-sol", prompt_tokens=241,
                                  completion_tokens=86, reasoning_tokens=32, feature="support-chat")

Set enabled=False in tests and local development to make both methods no-ops:

tracker = LLMtrack(api_key=os.environ["LLMTRACK_API_KEY"], enabled=False)

Constructor options

Event fields

The wrapper intentionally accepts the following snake-case subset of the IngestRequest contract. total_tokens, cached_input_tokens, and cache_write_tokens exist in the wire contract but are not arguments in the current Python public API; do not pass them to this SDK.

The client validates prompt_tokens, completion_tokens, and reasoning_tokens as non-negative integers and rejects metadata whose compact UTF-8 JSON serialization exceeds 8192 bytes. The server validates the remaining contract constraints.

Delivery, retries, and idempotency

Each call automatically receives a UUID v4 idempotency key. That key stays stable across retries, preventing double-counting when a stored response is lost. Supply your own stable key to deduplicate separate calls:

tracker.track(provider="openai", model="gpt-5.6-sol", prompt_tokens=241, completion_tokens=86,
              reasoning_tokens=32, feature="support-chat", idempotency_key="9ea0c2ec-7b98-4bc3-9802-20ae6a468a35")

The SDK retries only network failures, timeouts, and HTTP 5xx responses. It never retries HTTP 4xx responses.

Errors

track_sync() raises these errors. track() sends them to on_error and never raises.

Warnings and free-plan key binding

The most common reason events do not appear: free-plan keys bind to one provider/model/feature triple. Mismatched events are accepted and billed (or consume quota) but hidden. Match all three values to the binding shown in LLMtrack. NOT_DASHBOARD_VISIBLE includes the bound and submitted triples.

Troubleshooting

Events are not appearing

Check warnings for NOT_DASHBOARD_VISIBLE and compare provider, model, and feature with the key binding. A short-lived process can exit before the daemon thread finishes; use await track_sync() in scripts and jobs that must confirm delivery.

Cost shows 0

Check for UNKNOWN_MODEL or pricing_status: unknown_model. Use the exact response.model returned by the provider so active pricing can match it.

The key is rejected

Inspect LLMtrackError.code: replace invalid/revoked keys, reactivate inactive keys, and confirm the environment variable is available to the server process. Use await track_sync() to inspect the complete exception.

Contributing

Async tests use pytest-asyncio (included in the test and dev extras):

pip install -e 'packages/python[test]'
pytest packages/python/tests

More information

• LLMtrack documentation
• MIT License