Skip to main content
This page extends the architecture overview with the mechanics of ingestion: the standardised event every source maps to, the connector types, how cost is attached, and how metering is provisioned for you. The design goal is zero manual setup. You connect a source; Tirdad handles normalisation, pricing, and the creation of meters and features — you do not hand-write transforms, build a model price list, or define meters per model.

The standardised AI usage event

Every source (a LiteLLM webhook, a Langfuse trace, a Bedrock log, a Databricks usage row) is normalised to one canonical shape before anything else happens. It rides on Tirdad’s standard event (event_name, external_customer_id, properties, timestamp, source), with a fixed convention for AI properties.
Key fields:
Following Tirdad’s event format, all properties values are sent as strings; Tirdad interprets numeric fields during aggregation.

Connector types

Sources differ in whether they can push in real time, must be polled, or only expose aggregate totals. Tirdad covers all three with the same downstream pipeline.

Managed pull flow (e.g. Langfuse, Databricks, Bedrock)

Managed pull flow — a scheduled trigger reads each source since the last watermark via API, SQL, or object-store readers, transforms the result to ai.usage server-side, dedupes by request_id, and ingests into Tirdad.
You provide read-only credentials once; Tirdad stores them securely and runs the schedule. A per-source watermark plus request_id dedupe guarantees no double counting across overlapping pulls.

Integrating LiteLLM

LiteLLM is a real-time push source: it fires a logging callback on every completion, already carrying token counts, USD cost, model, and identity. There are three ways to wire it into Tirdad — from drop-in to fully custom — and all three emit the same standardised ai.usage event. You never define meters, features, or prices for this; enabling the LiteLLM connector with a template provisions them. Register the Tirdad callback and you’re done — no payload mapping, no transform to maintain. Every completion() call you already make is metered.
The callback reads LiteLLM’s per-request record, maps it to ai.usage, and ships it — one event per request, attributed to the team (with the user kept as a child for per-user and per-agent visibility).

Option 2 — LiteLLM Proxy (no code)

If you run the LiteLLM Proxy, enable the Tirdad callback in config.yaml. Every request routed through the proxy — from any app, agent, or MCP server — is metered and attributed to the virtual key’s team/user, with nothing to deploy in your services.

Option 3 — Custom callback (full control)

When you want to shape the event yourself — add tags, override the entity, or filter calls — implement a LiteLLM CustomLogger and send the event with the Tirdad SDK. This is exactly what Option 1 does under the hood, exposed for you to customise.

The event Tirdad receives

Whichever option you pick, the same canonical event lands — already mapped, ready to be priced and attributed:
If you’d rather not use an SDK at all, the same event can be posted directly to the events API:

Closing the loop — enforcement

Because Tirdad now holds the source of truth for spend, a budget breach can act back on LiteLLM (the dashed return path in the push-flow diagram). On a warning/critical alert, Tirdad calls LiteLLM’s management API with your master key to throttle the offending key or team:
Start with soft alerts (webhooks/notifications) and graduate to hard enforcement once you trust the numbers.

How cost is attached

Most modern gateways compute USD cost themselves, so Tirdad uses that by default and re-prices only when it needs to.
  • Trust the source cost (default) — when reported_cost is present (LiteLLM, OpenRouter, Portkey, Langfuse, Helicone, Cloudflare, Vercel), Tirdad stores it as-is. This correctly captures negotiated and BYOK rates.
  • Re-price from the catalog — when a source provides tokens only (Bedrock logs, Databricks token usage) or you want markup/margin or a single normalised price across gateways, Tirdad prices from its model pricing repository.
The public model pricing repository is refreshed daily, so popular provider/model rates are available out of the box. Override any rate per provider, model, or customer for committed pricing, and apply a markup factor when reselling.
How cost is attached — if the ai.usage event already carries reported_cost, Tirdad uses the source cost; otherwise (or when markup or normalised pricing is needed) it prices from the model pricing repository and applies overrides and markup, producing the charged cost on usage.

Auto-provisioning metering

Enabling a connector and choosing a template creates the metering graph for you — no manual meters, features, or prices.
  • cost_tracking — meters for input/output/cached/reasoning tokens and request count, features per dimension, and catalog pricing at cost. For internal showback.
  • team_budget — the above plus a wallet, a recurring monthly credit grant, and info/warning/critical alerts wired to gateway enforcement. For team and agent budgets.
  • resale_markup — catalog re-pricing with a configurable margin, plus margin analytics. For AI features you bill customers for.
Provider and model breakdowns come from filters and group_by on the provider and model properties, so there is no meter-per-model explosion — a handful of generic meters cover every model.

Identity and hierarchy resolution

Each connector maps source identifiers to a Tirdad billing entity and, optionally, builds the hierarchy:
  • A primary field (for example raw_team) resolves to the customer being metered.
  • Additional fields (raw_user, agent_id) create child entities under it, using Customer Hierarchy for individual visibility with consolidated rollups and shared wallets.
  • Unrecognised identifiers can auto-create entities or map to an existing external_id.
This is what lets one wallet span an entire team while you still see each user’s and agent’s usage separately — and what powers per-agent ROI.

Source coverage

Phase one deliberately spans every connector type so the model is proven against the hard cases:
Coverage expands continuously — Helicone, OpenRouter, Portkey, Snowflake Cortex, TrueFoundry, Cloudflare, Vercel, and SAP Joule follow the same connector model. Each new source is a connector definition plus pricing entries, not a change to your setup.
Aggregate sources (such as Agentforce and SAP Joule) report coarse, native-unit totals rather than per-request tokens. Tirdad labels these with fidelity: aggregate so dashboards and alerts reflect the real granularity — treat per-agent ROI from these sources as approximate.

AI Cost Tracking overview

The problem, the solution, and the high-level architecture.

Send Usage Events

The underlying event pipeline AI usage rides on.

Alerts and Notifications

Spend thresholds, states, and webhook delivery.