> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tirdad.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ingesting AI Usage

> A technical look at how Tirdad normalises usage from any AI gateway or provider into a single standardised event, attaches cost, and auto-provisions metering — across real-time push, managed pull, and aggregate sources.

This page extends the [architecture overview](https://docs.tirdad.ai/docs/ai-cost-tracking/overview#architecture) 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](https://docs.tirdad.ai/docs/core-concepts/send-usage-events) (`event_name`, `external_customer_id`, `properties`, `timestamp`, `source`), with a fixed convention for AI properties.

```json theme={null}
{
  "event_name": "ai.usage",
  "external_customer_id": "team_platform",
  "timestamp": "2026-06-14T10:30:00Z",
  "source": "litellm",
  "properties": {
    "provider": "anthropic",
    "model": "claude-opus-4-8",
    "operation": "chat",
    "input_tokens": "1840",
    "output_tokens": "320",
    "cached_tokens": "1024",
    "reasoning_tokens": "0",
    "reported_cost": "0.041",
    "request_id": "req_abc123",
    "raw_user": "u_91",
    "raw_team": "team_platform",
    "agent_id": "agent_support_bot",
    "fidelity": "per_request"
  }
}
```

Key fields:

| Field | Purpose |
| - | - |
| `provider`, `model`, `operation` | Drive model pricing and let analytics break down by provider/model/token type. |
| `input_tokens`, `output_tokens`, `cached_tokens`, `reasoning_tokens` | Token-level usage; `unit`/`quantity` are used for non-token sources (characters, seconds, requests, credits). |
| `reported_cost` | The source's own computed cost in USD, when it provides one (most gateways do). |
| `raw_user`, `raw_team`, `agent_id`, `tags` | Source identifiers used to resolve the billing entity and hierarchy. |
| `fidelity` | `per_request` or `aggregate` — records the granularity a source can offer, so analytics stays honest. |

> [!NOTE]
>
> 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.

| Type | How it works | Best for | Latency |
| - | - | - | - |
| **Push** | The source sends each request to Tirdad as it happens, through the Tirdad SDK callback or a webhook. | Real-time sources. | Real-time |
| **Managed pull** | Tirdad runs a scheduled job that reads the source over API, SQL, or object storage, transforms server-side, and ingests. | API/SQL/log-reachable SaaS and clouds — **no deployment**. | Seconds to hours |
| **Aggregate** | Tirdad ingests periodic exports (dashboard/email/usage views) and converts native units to cost. | Sources with no per-request API. | Daily |

### 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.](https://mintcdn.com/tirdad/gw0QR5klPZER5Lac/images/docs/ai-cost-tracking/managed-pull-flow.png?fit=max\&auto=format\&n=gw0QR5klPZER5Lac\&q=85\&s=b3863c95bc636b1d317a1dd3d410962a)

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](#auto-provisioning-metering) provisions them.

### Option 1 — Tirdad SDK callback (recommended)

Register the Tirdad callback and you're done — no payload mapping, no transform to maintain. Every `completion()` call you already make is metered.

```python theme={null}
import litellm
from tirdad_sdk.litellm import TirdadLogger

litellm.callbacks = [
    TirdadLogger(
        api_key="<TIRDAD_API_KEY>",
        # which LiteLLM identity becomes the Tirdad billing entity
        entity_from="metadata.user_api_key_team_id",
    )
]

# nothing else changes — usage now flows to Tirdad on every call
litellm.completion(
    model="anthropic/claude-opus-4-8",
    messages=[{"role": "user", "content": "Summarise this ticket"}],
    metadata={"user_api_key_team_id": "team_platform", "user_api_key_user_id": "u_91"},
)
```

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.

```yaml theme={null}
litellm_settings:
  callbacks: ["tirdad"]

environment_variables:
  TIRDAD_API_KEY: "<TIRDAD_API_KEY>"
  # map a LiteLLM virtual-key dimension to the billing entity
  TIRDAD_ENTITY_FROM: "metadata.user_api_key_team_id"
```

### 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.

```python theme={null}
from litellm.integrations.custom_logger import CustomLogger
import litellm
from tirdad_sdk import Tirdad

fp = Tirdad(api_key="<TIRDAD_API_KEY>")

class TirdadLogger(CustomLogger):
    async def async_log_success_event(self, kwargs, response_obj, start_time, end_time):
        # LiteLLM's normalised, per-request usage + cost record
        slp = kwargs["standard_logging_object"]
        meta = slp.get("metadata", {})

        fp.events.ingest(
            event_name="ai.usage",
            external_customer_id=meta.get("user_api_key_team_id", "unknown"),
            source="litellm",
            properties={
                "provider": slp["custom_llm_provider"],
                "model": slp["model"],
                "operation": "chat",
                "input_tokens": slp["prompt_tokens"],
                "output_tokens": slp["completion_tokens"],
                "reported_cost": slp["response_cost"],   # USD, computed by LiteLLM
                "request_id": slp["id"],
                "raw_user": meta.get("user_api_key_user_id"),
                "raw_team": meta.get("user_api_key_team_id"),
            },
        )

litellm.callbacks = [TirdadLogger()]
```

### The event Tirdad receives

Whichever option you pick, the same canonical event lands — already mapped, ready to be priced and attributed:

```json theme={null}
{
  "event_name": "ai.usage",
  "external_customer_id": "team_platform",
  "source": "litellm",
  "properties": {
    "provider": "anthropic",
    "model": "claude-opus-4-8",
    "operation": "chat",
    "input_tokens": "1840",
    "output_tokens": "320",
    "reported_cost": "0.041",
    "request_id": "req_abc123",
    "raw_user": "u_91",
    "raw_team": "team_platform"
  }
}
```

If you'd rather not use an SDK at all, the same event can be posted directly to the [events API](https://docs.tirdad.ai/docs/core-concepts/usage-events/sending-events.md):

```bash theme={null}
curl -X POST https://api.tirdad.ai/v1/events \
  -H 'x-api-key: <TIRDAD_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "event_name": "ai.usage",
    "external_customer_id": "team_platform",
    "source": "litellm",
    "properties": {
      "provider": "anthropic", "model": "claude-opus-4-8",
      "input_tokens": "1840", "output_tokens": "320",
      "reported_cost": "0.041", "request_id": "req_abc123"
    }
  }'
```

### 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](https://docs.tirdad.ai/docs/customers/threshold-notifications.md), Tirdad calls LiteLLM's management API with your master key to throttle the offending key or team:

```bash theme={null}
# soft: zero out the remaining budget on a key
curl -X POST https://<litellm-proxy>/key/update \
  -H 'Authorization: Bearer <LITELLM_MASTER_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{ "key": "<virtual-key>", "max_budget": 0 }'

# hard: block the key outright
curl -X POST https://<litellm-proxy>/key/block \
  -H 'Authorization: Bearer <LITELLM_MASTER_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{ "key": "<virtual-key>" }'
```

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.](https://mintcdn.com/tirdad/gw0QR5klPZER5Lac/images/docs/ai-cost-tracking/cost-attachment.png?fit=max\&auto=format\&n=gw0QR5klPZER5Lac\&q=85\&s=247a875b8eccd25e191dce1288753c52)

## 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](https://docs.tirdad.ai/docs/customers/threshold-notifications.md) 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](https://docs.tirdad.ai/docs/customers/overview.md) being metered.
* Additional fields (`raw_user`, `agent_id`) create child entities under it, using [Customer Hierarchy](https://docs.tirdad.ai/docs/subscriptions/customer-hierarchy.md) 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:

| Source | Type | Cost basis | Notes |
| - | - | - | - |
| **LiteLLM** | Push (or hosted webhook) | Source cost | Richest identity (key/user/team/org/tags); real-time. |
| **Langfuse** | Managed pull (observations API) | Source cost | No usage webhook upstream, so polled; near-real-time. |
| **AWS Bedrock** | Managed pull (S3 logs + CUR) | Catalog re-price | Per-request token logs; reconcile \$ against Cost & Usage Report. |
| **Databricks** | Managed pull (system tables, SQL) | Catalog re-price | DBU/token usage joined to list prices; hourly grain. |
| **Salesforce Agentforce** | Aggregate | Catalog (rate card) | Native units (credits/conversations); `fidelity: aggregate`. |

> [!NOTE]
>
> 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.

> [!WARNING]
>
> 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.

## Related

> [card] [AI Cost Tracking overview](https://docs.tirdad.ai/docs/ai-cost-tracking/overview)
>
> The problem, the solution, and the high-level architecture.

> [card] [Send Usage Events](https://docs.tirdad.ai/docs/core-concepts/send-usage-events)
>
> The underlying event pipeline AI usage rides on.

> [card] [Alerts and Notifications](https://docs.tirdad.ai/docs/customers/threshold-notifications.md)
>
> Spend thresholds, states, and webhook delivery.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.