# How Maka Tracks Token Usage and Project Costs: A Complete Technical Guide

> Maka tracks token usage and project costs by emitting session events, looking up pricing, computing call costs, and aggregating into reports. Learn how in this technical guide.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: deep-dive
- Published: 2026-08-31

---

**Maka tracks token usage by emitting `token_usage` session events after each model interaction, looking up per-model pricing from a metadata catalog, computing per-call costs in USD, and aggregating these values into session and project-level cost reports.**

The Apache Maka project implements a comprehensive **token usage tracking** and **project cost calculation** pipeline that records every interaction with a language model. This system enables precise cost attribution for AI-powered applications, giving developers visibility into their spending across model providers and project runs.

## Token Usage Event Creation

Every model interaction in Maka is captured as a session event. When a language model returns a response, the runtime kernel emits a `token_usage` event containing the input and output token counts.

In [`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts) at line 1013, the kernel emits this event after the model stream finishes:

```typescript
emit({
  type: 'token_usage',
  input: nInput,
  output: nOutput,
  total: nInput + nOutput,
  runtimeSteps: 1,
  ts: Date.now(),
});

```

The event type is formally defined in [`packages/core/src/events.ts`](https://github.com/apache/maka/blob/main/packages/core/src/events.ts) at line 1065 as `type: 'token_usage'`, ensuring type safety across the codebase.

This event captures the raw token consumption data that serves as the foundation for all subsequent cost calculations.

## Model Price Lookup and Cost Attribution

To translate tokens into monetary cost, Maka maintains a **model metadata catalog** with pricing information for supported providers. The `sync-model-metadata.mjs` script (lines 636-647) loads this data and provides helper functions for cost retrieval:

```typescript
const inputUsdPer1M  = priceNumber(provider, modelId, cost.input,  'input');
const outputUsdPer1M = priceNumber(provider, modelId, cost.output, 'output');

```

These rates represent the price per 1 million tokens for both input and output, as published by model providers.

Using these rates, the runtime computes a `costUsd` value for each call. This calculation happens in [`packages/runtime/src/runtime-event-read-model.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-read-model.ts), where events are enriched with financial data:

```typescript
// Compute cost for this call
const callCostUsd =
  (event.input / 1_000_000) * inputRate +
  (event.output / 1_000_000) * outputRate;

// Attach cost to the event
event.costUsd = callCostUsd;
event.costBasis = 'priced';

```

The `costBasis` field distinguishes between:
- ** `'priced'`** — cost was successfully calculated using known pricing data
- **`'unpriced'`** — pricing information was unavailable for this model

This distinction prevents missing pricing data from silently inflating reported costs with zero values.

## Session-Level Cost Aggregation

As a session progresses, the **session manager** aggregates individual `token_usage` events into running totals. In [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts), this aggregation sums the `costUsd` values across all token usage events:

```typescript
session.costUsd = session.events
  .filter(e => e.type === 'token_usage')
  .reduce((sum, e) => sum + (e.costUsd ?? 0), 0);

```

The test suite in [`packages/runtime/src/__tests__/session-trace-projection.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/session-trace-projection.test.ts) (lines 56-58 and 115-116) validates this behavior, verifying that aggregated usage records contain the expected `costUsd` and `costBasis` fields.

This aggregation produces an accurate running total that updates throughout the session lifecycle.

## Project-Level Cost Reporting

Aggregated usage data persists in the **project ledger**, Maka's durable storage for historical run data. The **PI (Project Insight)** subsystem surfaces this information through both the UI and CLI, giving developers real-time visibility into their spending.

The ledger's design handles edge cases gracefully:
- **Priced calls** contribute their calculated `costUsd` to totals
- **Unpriced calls** are tracked separately to maintain transparency about data quality
- **Mixed sessions** partially contribute when some model pricing is available

This architecture ensures that **project cost tracking** remains accurate even as model providers update pricing or new models are introduced without immediate cost data.

## Token Usage Tracking Pipeline

```typescript
// Complete flow: model response → cost calculation → aggregation

// 1. Kernel emits token usage (runtime-kernel.ts)
const tokenEvent = emit({
  type: 'token_usage',
  input: 120,
  output: 30,
  total: 150,
  ts: Date.now(),
});

// 2. Pricing lookup (sync-model-metadata.mjs)
const modelCost = lookupPricing(provider, modelId);
const inputRate = modelCost.input;   // e.g., $2.50 per 1M tokens
const outputRate = modelCost.output; // e.g., $10.00 per 1M tokens

// 3. Cost computation (runtime-event-read-model.ts)
tokenEvent.costUsd = (120/1e6 * inputRate) + (30/1e6 * outputRate);
tokenEvent.costBasis = 'priced';

// 4. Session aggregation (session-manager.ts)
session.totalCostUsd += tokenEvent.costUsd;

// 5. Project persistence (project ledger)
persistToLedger(session);

```

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts) | Emits `token_usage` events after model streams complete |
| [`packages/core/src/events.ts`](https://github.com/apache/maka/blob/main/packages/core/src/events.ts) | Defines the `token_usage` event type contract |
| `scripts/sync-model-metadata.mjs` | Loads and updates model pricing metadata |
| [`packages/runtime/src/runtime-event-read-model.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-read-model.ts) | Enriches events with computed cost data |
| [`packages/runtime/src/__tests__/session-trace-projection.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/session-trace-projection.test.ts) | Validates cost field presence on usage records |
| [`packages/runtime/src/__tests__/session-manager.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/session-manager.test.ts) | Tests session-level cost aggregation |

## Summary

- **Event-driven architecture**: Every model interaction generates a `token_usage` event with raw token counts
- **External pricing source**: Model costs are loaded from a metadata catalog, not hardcoded
- **Explicit cost basis**: The `costBasis` field tracks data quality and prevents misleading totals
- **Hierarchical aggregation**: Costs roll up from individual calls → sessions → project-level reports
- **PI subsystem integration**: Costs surface in both UI and CLI for operational visibility

## Frequently Asked Questions

### How does Maka handle models without known pricing?

Maka marks these calls with `costBasis: 'unpriced'` and excludes them from cost totals. This prevents unreliable estimates from distorting financial reports while maintaining transparency about coverage gaps.

### Where does Maka's pricing data come from?

The `sync-model-metadata.mjs` script maintains the **model-metadata** catalog, which aggregates official pricing from providers. This externalized approach allows pricing updates without code changes.

### Can developers override or customize pricing calculations?

The source architecture supports custom pricing through the model metadata system. Developers can extend the catalog or implement alternative `priceNumber` logic for private model deployments or negotiated rate cards.

### What happens if a session is interrupted mid-run?

Partial session data is preserved in the project ledger. The aggregation logic in [`session-manager.ts`](https://github.com/apache/maka/blob/main/session-manager.ts) only sums completed `token_usage` events, so interrupted runs report costs for confirmed interactions only.