One ingest contract. Every server runtime.

The hosted base URL is https://traket.ai. Send usage only from trusted server code.

Send the project-scoped SDK write key as a bearer token. The Catalog endpoint is public and requires no authorization.

Authorization: Bearer traket_live_...
Content-Type: application/json

Submit a JSON object with one events array. The endpoint processes every item independently after request-level authentication and limit checks.

curl --request POST \
  https://traket.ai/api/v1/usage/events \
  --header "Authorization: Bearer traket_live_..." \
  --header "Content-Type: application/json" \
  --data '{
    "events": [
      {
        "provider": "openai",
        "externalCustomerId": "cus_123",
        "environment": "production",
        "feature": "support_reply",
        "operation": "responses.create",
        "model": "gpt-5.4-mini",
        "idempotencyKey": "response_01J...",
        "usage": {
          "input_tokens": 1280,
          "input_tokens_details": { "cached_tokens": 640 },
          "output_tokens": 220,
          "output_tokens_details": { "reasoning_tokens": 80 },
          "total_tokens": 1500
        }
      }
    ]
  }'

The documented wire contract uses the fields below. Unknown top-level fields are ignored except legacy customerId, which is explicitly rejected. Traket accepts usage and attribution metadata only, never prompt or model-output content.

Cost object

Send cost when your provider or gateway already knows the charge. A valid explicit amount wins over a catalog estimate.

Units array

Every event receives one request unit automatically. Use the optional array for additional billable quantities.

OpenAI-style usage

OpenAI and Azure OpenAI events normalize these fields into token units. Known catalog models can receive a local USD estimate when no explicit cost is supplied.

externalCustomerId is required and must be a Stripe customer ID beginning with cus_. Before live metering, import or connect Stripe so that identity resolves to exactly one customer in the write key's project.

A response envelope reports new inserts in accepted, event failures in rejected, and the outcome of every submitted index in results. Duplicate events appear only in results.

{
  "accepted": 1,
  "rejected": 1,
  "results": [
    {
      "eventId": "b06c67d5-...",
      "index": 0,
      "status": "inserted"
    },
    {
      "eventId": "90ef2161-...",
      "index": 1,
      "status": "duplicate"
    },
    {
      "error": "Stripe customer cus_missing is not imported into this project.",
      "index": 2,
      "status": "rejected"
    }
  ]
}

Authenticated project abuse ceilings use fixed one-minute buckets. Submitted requests and event counts consume the bucket before per-event validation, so rejected rows still count.

A separate in-process client-address ceiling allows 20,000 requests per minute. It dampens obvious unauthenticated floods before project-level quota enforcement.

• On 429, wait for the integer seconds in Retry-After.
• Authenticated quota responses also include X-Traket-Ingest-Limit-Class.
• Retry network failures, timeouts, 408, 429, and 5xx with bounded exponential jitter.
• Preserve each event's idempotency key across every retry.

When idempotencyKey is omitted, SDKs assign one before delivery and the raw API derives a stable payload hash. Supplying a provider request or response ID is safer when the same logical event might be reconstructed differently.

The public Catalog endpoint returns the accepted provider IDs and the base OpenAI-family models that have local pricing. It is a pricing catalog, not a model allowlist.

GET https://traket.ai/api/v1/usage/catalog

{
  "modelCatalogVersion": "openai-text-2026-07-19",
  "providers": [
    {
      "id": "openai",
      "label": "OpenAI",
      "modelPolicy": "catalog",
      "notes": "Listed base models and their date-suffixed snapshots are priced locally; other unknown IDs are stored without an estimate.",
      "models": [
        "gpt-4.1",
        "gpt-4.1-mini",
        "gpt-4.1-nano"
      ]
    },
    {
      "id": "azure_openai",
      "label": "Azure OpenAI",
      "modelPolicy": "catalog",
      "notes": "Send the underlying OpenAI model, not only an Azure deployment name; listed bases and date-suffixed snapshots use local pricing.",
      "models": [
        "gpt-4.1",
        "gpt-4.1-mini",
        "gpt-4.1-nano"
      ]
    }
  ]
}

Current model catalog version: openai-text-2026-07-19.

Locally priced OpenAI-family models in this build:

Traket never collects or stores prompts, messages, model outputs, or full provider request and response bodies. There is no prompt-capture mode. Only usage counts, costs, operational identifiers, and customer attribution are sent to Traket.

• Never send prompts, messages, model output, files, images, tool arguments, full provider responses, or provider headers.
• Never send API keys, authorization values, passwords, secrets, or tokens.
• Metadata is limited to 24 scalar entries. Keys are trimmed to 64 characters and string values to 512 characters.
• A direct API event is rejected when a metadata key resembles private content or credentials.