Traket
Overview

Quickstart

Get started with Traket usage metering.

Upload SDKs

Traket records server-side AI usage events so your dashboard can show request counts, model spend, tokens, feature cost, customer attribution, and waste signals. The SDKs send metering fields only: never prompts, outputs, headers, API keys, or full provider responses.

Pick the integration with the amount of control you need:

ApproachBest forWhy
SDKMost appsTyped helpers, batching, metadata sanitization
OpenAI wrapperOpenAI call sitesCaptures usage and IDs without provider payloads
Events APICustom gatewaysAny backend language, no package dependency
Looking for historical data? Use CSV imports for backfill, and use SDK writes for live request-level metering.
01

Install

Install the client for your runtime. The TypeScript SDK is published as @traket/sdk, Python astraket-sdk, and Go asgithub.com/traketai/traket-go.

Package install
pnpm add @traket/sdk
pip install traket-sdk
go get github.com/traketai/traket-go
02

Authenticate

Create a project-scoped SDK write key in the dashboard, then store it in your server environment. The plaintext key is shown once at creation time.

Environment
TRAKET_WRITE_KEY=sm_live_...
TRAKET_ENDPOINT=https://traket.ai/api/v1/usage/events
Keep the write key server-side. Do not import Traket SDK clients into browser components or mobile apps.
03

Using the client SDKs

Send stable business identifiers on every event. Use the same customer ID you use for Stripe imports whenever possible so Traket can compare revenue against AI cost.

TypeScript / JavaScript
import { createMargins } from "@traket/sdk";

const margins = createMargins({
  endpoint: process.env.TRAKET_ENDPOINT,
  writeKey: process.env.TRAKET_WRITE_KEY!,
});

await margins.track({
  provider: "openai",
  externalCustomerId: "user_123",
  feature: "generate_blog_post",
  model: "gpt-5.4-mini",
  cost: {
    amount: aiCallCost,
    currency: "usd",
    source: "manual_override",
  },
});
Python
import os

from traket import create_margins

margins = create_margins(
    write_key=os.environ["TRAKET_WRITE_KEY"],
    endpoint=os.getenv("TRAKET_ENDPOINT"),
)

margins.track({
    "provider": "openai",
    "external_customer_id": "user_123",
    "feature": "generate_blog_post",
    "model": "gpt-5.4-mini",
    "cost": {
        "amount": ai_call_cost,
        "currency": "usd",
        "source": "manual_override",
    },
})
margins.flush()
Go
client, err := traket.NewClient(traket.Options{
    WriteKey: os.Getenv("TRAKET_WRITE_KEY"),
    Endpoint: os.Getenv("TRAKET_ENDPOINT"),
})
if err != nil {
    return err
}

_, err = client.Track(ctx, traket.UsageCaptureEvent{
    Provider:           "openai",
    ExternalCustomerID: "user_123",
    Feature:            "generate_blog_post",
    Model:              "gpt-5.4-mini",
    Cost: &traket.UsageCost{
        Amount:   aiCallCost,
        Currency: "usd",
        Source:   "manual_override",
    },
})
if err != nil {
    return err
}

_, _ = client.Flush(ctx)
04

Using the OpenAI wrapper

The OpenAI wrapper returns the original provider response. On success, it records model, duration, request IDs, status, and usage fields. On failure, it records an error event and rethrows or returns the original error.

TypeScript / JavaScript
const response = await margins.openai.track(
  () => openai.responses.create({ model: "gpt-5.4-mini", input }),
  {
    externalCustomerId: user.id,
    environment: process.env.NODE_ENV,
    feature: "generate_blog_post",
    promptType: "blog_post",
  },
);
Python
response = margins.openai.track(
    lambda: client.responses.create(model="gpt-5.4-mini", input=user_input),
    {
        "external_customer_id": user.id,
        "environment": "production",
        "feature": "generate_blog_post",
        "prompt_type": "blog_post",
    },
)
Go
response, err := traket.TrackOpenAI(ctx, client, func(ctx context.Context) (any, error) {
    return openaiClient.Responses.New(ctx, request)
}, traket.OpenAIAttribution{
    ExternalCustomerID: userID,
    Environment:        "production",
    Feature:            "generate_blog_post",
    PromptType:         "blog_post",
})
05

Batch tracking

Use batch tracking in workers, queues, or provider gateways that collect multiple rows before sending them to Traket. Each ingest request accepts 1 to 100 events.

Batch events
await margins.trackBatch({
  events: rows.map((row) => ({
    provider: row.provider,
    model: row.model,
    externalCustomerId: row.userId,
    feature: row.feature,
    cost: row.costUsd
      ? { amount: row.costUsd, currency: "usd", source: "manual_override" }
      : undefined,
  })),
});
06

Using the Events API

You can post directly to the ingest endpoint from any backend runtime. The write key maps every accepted event to the correct Traket project.

HTTP request
POST /api/v1/usage/events
Authorization: Bearer sm_live_...
Content-Type: application/json

{
  "events": [
    {
      "provider": "openai",
      "externalCustomerId": "user_123",
      "feature": "support_reply",
      "model": "gpt-5.4-mini"
    }
  ]
}
07

Event fields

providerRequired provider slug from the allowed provider list
externalCustomerIdYour app user, tenant, workspace, or Stripe customer ID
customerIdInternal Traket customer UUID only
featureStable product feature slug, such as support_reply
modelProvider model name
operationProvider method or gateway operation
promptTypeStable prompt or template slug
usageOpenAI-style usage object when available
costExplicit known cost
idempotencyKeyStable request, job, run, or provider ID
08

Allowed providers and models

Live SDK ingest accepts the provider slugs below. OpenAI and Azure OpenAI model names are checked against the local pricing catalog; other allowed providers accept provider-reported model IDs until dedicated pricing catalogs are added.

Catalog endpoint: /api/v1/usage/catalog. Version: openai-text-2026-05-22.

openaiOpenAIcatalog

Model must match the local OpenAI pricing catalog.

gpt-4.1gpt-4.1-minigpt-4.1-nanogpt-4ogpt-4o-minigpt-5gpt-5-minigpt-5-nanogpt-5.1gpt-5.2gpt-5.3-codexgpt-5.4gpt-5.4-minigpt-5.4-nanogpt-5.4-progpt-5.5gpt-5.5-proo1o1-minio1-proo3o3-minio3-proo4-mini
azure_openaiAzure OpenAIcatalog

Send the underlying OpenAI model, not only an Azure deployment name.

gpt-4.1gpt-4.1-minigpt-4.1-nanogpt-4ogpt-4o-minigpt-5gpt-5-minigpt-5-nanogpt-5.1gpt-5.2gpt-5.3-codexgpt-5.4gpt-5.4-minigpt-5.4-nanogpt-5.4-progpt-5.5gpt-5.5-proo1o1-minio1-proo3o3-minio3-proo4-mini
anthropicAnthropiccustom

Provider is allowed; model names are accepted as reported.

aws_bedrockAWS Bedrockcustom

Provider is allowed; Bedrock model IDs are accepted as reported.

google_vertexGoogle Vertexcustom

Provider is allowed; Vertex model IDs are accepted as reported.

mistralMistralcustom

Provider is allowed; model names are accepted as reported.

openrouterOpenRoutercustom

Provider is allowed; routed model IDs are accepted as reported.

otherOthercustom

Use only when a supported provider does not fit yet.

09

Privacy contract

Never send prompts, messages, model outputs, images, files, tool arguments, full provider responses, provider headers, API keys, authorization headers, passwords, secrets, or tokens.

SDKs sanitize suspicious metadata keys, but application code should still pass only allowlisted scalar operational metadata such as region, route, tenant tier, or experiment name.

10

Publish language SDKs

Publish Python to PyPI from packages/sdk-python. Use TestPyPI first by adding --repository testpypi.

PyPI upload
python -m pip install --upgrade build twine
cd packages/sdk-python
python -m build
python -m twine upload dist/*

Go modules are published by pushing a public Git tag. Copypackages/sdk-go to the publicgithub.com/traketai/traket-go repository, then tag and push the release.

Go module release
git tag v0.1.0
git push origin main --tags
go get github.com/traketai/[email protected]