Skip to main content

Ai Token Tracker Python SDK

ai-token-tracker captures outbound LLM traffic and posts ingest envelopes to Ai Token Tracker.

Supports:

  1. Automatic HTTP interception (requests, httpx sync/async)
  2. SDK wrapper integration (begin_llm_call scope)

Requirements

  • Python 3.10+

Installation

pip install ai-token-tracker

Optional extras:

pip install ai-token-tracker[requests]
pip install ai-token-tracker[httpx]
pip install ai-token-tracker[all]

Defaults

  • enable_auto_interception=True

Quick Start (Plain Script)

from ai_token_tracker import (
    AiTokenTrackerIngestionClient,
    AiTokenTrackerOptions,
    AiTokenTrackerSdkClient,
)

ingestion = AiTokenTrackerIngestionClient(
    AiTokenTrackerOptions(auth_token="atk_your_key")
)

sdk = AiTokenTrackerSdkClient(ingestion)

scope = sdk.begin_llm_call(
    request={"model": "gpt-4.1-mini", "input": "hello"},
    additional_custom_filters={"workflow": "quickstart"},
    provider_hint="anthropic",
)

try:
    provider_response = {"id": "resp_123", "output": [{"type": "output_text", "text": "hi"}]}
    scope.complete(provider_response, status_code=200)
except Exception as ex:
    scope.fail(ex, status_code=500)
    raise
finally:
    ingestion.close()

Automatic HTTP Interception

Interception is explicit install + option-gated:

import requests
from ai_token_tracker import (
    AiTokenTrackerIngestionClient,
    AiTokenTrackerOptions,
    install_http_interception,
)

client = AiTokenTrackerIngestionClient(
    AiTokenTrackerOptions(
        auth_token="atk_your_key",
        enable_auto_interception=True,
    )
)

install_http_interception(client)

# Classified request is captured and ingested automatically.
requests.post(
    "https://api.openai.com/v1/responses",
    headers={"Authorization": "Bearer sk_test"},
    json={"model": "gpt-4.1-mini", "input": "hello"},
    timeout=10,
)

client.close()  # unpatches interceptors + shuts down background worker

Scoped Custom Filters For Automatic Interception

Use interception scope to attach custom filters without wrapper integration:

import requests
from ai_token_tracker import (
    AiTokenTrackerIngestionClient,
    AiTokenTrackerInterceptionScope,
    AiTokenTrackerOptions,
    install_http_interception,
)

client = AiTokenTrackerIngestionClient(
    AiTokenTrackerOptions(auth_token="atk_your_key", enable_auto_interception=True)
)
install_http_interception(client)

scope = AiTokenTrackerInterceptionScope.create({"workflow": "social_post_generation"})
scope.add_custom_filters({"job_id": "job-42", "customer_id": "cust-19"})

try:
    requests.post(
        "https://api.openai.com/v1/responses",
        headers={"Authorization": "Bearer sk_test"},
        json={"model": "gpt-4.1-mini", "input": "hello"},
        timeout=10,
    )
finally:
    scope.close()

create(...) opens scope automatically. Call close() when you want to end scope early.

SDK Wrapper Example

from ai_token_tracker import AiTokenTrackerIngestionClient, AiTokenTrackerOptions, AiTokenTrackerSdkClient

ingestion = AiTokenTrackerIngestionClient(AiTokenTrackerOptions(auth_token="atk_your_key"))
tracker = AiTokenTrackerSdkClient(ingestion)

scope = tracker.begin_llm_call(
    request={"model": "claude-sonnet-4-6", "max_tokens": 256, "messages": [{"role": "user", "content": "hello"}]},
    additional_custom_filters={"tenant": "acme", "job": "summarization"},
    provider_hint="anthropic",
)

scope.complete({"id": "msg_123"}, status_code=200)
ingestion.close()

FastAPI Example

from contextlib import asynccontextmanager
from fastapi import FastAPI
from ai_token_tracker import (
    AiTokenTrackerIngestionClient,
    AiTokenTrackerOptions,
    AiTokenTrackerSdkClient,
    install_http_interception,
)

ingestion = AiTokenTrackerIngestionClient(
    AiTokenTrackerOptions(auth_token="atk_your_key", enable_auto_interception=True)
)
tracker = AiTokenTrackerSdkClient(ingestion)

@asynccontextmanager
async def lifespan(app: FastAPI):
    install_http_interception(ingestion)
    yield
    ingestion.close()

app = FastAPI(lifespan=lifespan)

@app.get("/health")
def health() -> dict[str, str]:
    return {"status": "ok"}

Background Worker / Job Pipeline Example

from ai_token_tracker import AiTokenTrackerIngestionClient, AiTokenTrackerOptions, AiTokenTrackerSdkClient

ingestion = AiTokenTrackerIngestionClient(AiTokenTrackerOptions(auth_token="atk_your_key"))
tracker = AiTokenTrackerSdkClient(ingestion)

def run_job(job_id: str, prompt: str) -> None:
    scope = tracker.begin_llm_call(
        request={"model": "gpt-4.1-mini", "input": prompt},
        additional_custom_filters={"job_id": job_id, "pipeline": "nightly"},
        provider_hint="anthropic",
    )
    try:
        response = {"id": f"resp_{job_id}", "output": [{"type": "output_text", "text": "done"}]}
        scope.complete(response)
    except Exception as ex:
        scope.fail(ex)
        raise

run_job("42", "summarize daily usage")
ingestion.close()

Custom Filters Guidance

additional_custom_filters is key/value metadata attached to each envelope:

  • keep keys stable (tenant, workflow, job_id, environment)
  • keep values low-cardinality when possible
  • avoid putting secrets or full prompt bodies in filters

Verification Checklist

  1. Create client with valid auth_token.
  2. For interception, set option flag and call install_http_interception(client).
  3. Send known LLM request (/v1/responses or /chat/completions).
  4. Confirm event appears in AI Token Tracker dashboard.
  5. Confirm app flow still works if ingest is unavailable (tracking paths are non-throwing).

Public API Summary

  • AiTokenTrackerOptions(auth_token, enable_auto_interception=True)
  • AiTokenTrackerIngestionClient.track(...) -> TrackResult
  • AiTokenTrackerIngestionClient.track_async(...) -> TrackResult
  • AiTokenTrackerIngestionClient.close()
  • AiTokenTrackerInterceptionScope.create(...), open(), close()
  • AiTokenTrackerSdkClient.begin_llm_call(...) -> CallScope
  • CallScope.complete(...), CallScope.fail(...)
  • CallScope.complete_async(...), CallScope.fail_async(...)
  • install_http_interception(client), uninstall_http_interception(client)

Metadata

Release files for ai-token-tracker 0.2.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ai-token-tracker 0.2.7
File Size Uploaded Provenance Actions
ai_token_tracker-0.2.7.tar.gz 18.2 kB Without provenance Details for ai_token_tracker-0.2.7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ai-token-tracker 0.2.7
File Interpreter ABI Platform Actions
ai_token_tracker-0.2.7-py3-none-any.whl Python 3 none any Details for ai_token_tracker-0.2.7-py3-none-any.whl

Total release size: 34.7 kB

Release files / ai_token_tracker-0.2.7.tar.gz

Download URL ai_token_tracker-0.2.7.tar.gz
Size 18.2 kB
Tags Source
SHA-256 checksum
How to use checksums
7c531831e7ad7353fd38aea134148f02b989414a97de1e1cac566bee60060f2a
BLAKE2b-256 checksum
How to use checksums
fafeaa23bb249c301c05440d0815b4543b047ec97f932aabe7716c4f6384e1d9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / ai_token_tracker-0.2.7-py3-none-any.whl

Download URL ai_token_tracker-0.2.7-py3-none-any.whl
Size 16.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
596338b7a7445543747c55d0000e83f7f26368d8194a5903f1f466f10a9e56cd
BLAKE2b-256 checksum
How to use checksums
671fb0c63807cbc09d25152defdeb9e45e435b3d8f42ba9aee64f2706cf5c7e7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Security for ai-token-tracker 0.2.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page