# How Cost Tracking Works for Voice Control Sessions in God’s Eye View

> Discover how God's Eye View tracks voice control session costs using a three-tier architecture. Monitor OpenAI API usage in real dollar amounts with flexible limits and warnings.

- Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view)
- Tags: internals
- Published: 2026-08-29

---

**Cost tracking for voice control sessions in God’s Eye View relies on a three-tier architecture: a model registry with USD-per-million-token rates, configurable spend-guard limits, and a stateful session tracker that converts OpenAI Realtime API usage into running dollar amounts with soft warnings and hard caps.**

God’s Eye View implements defensive cost accounting to prevent runaway spending during voice-controlled AI sessions. The system intercepts every `response.done` event from the OpenAI Realtime API, converts token usage into precise USD costs, and enforces tier-specific limits that trigger UI alerts or automatic session termination. This implementation spans [`src/voice/voiceCost.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/voiceCost.js) for rate calculations and [`src/voice/gevRealtime.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/gevRealtime.js) for session orchestration.

## Voice Cost Architecture

The cost tracking system combines three tightly coupled components to provide real-time spend visibility and protection.

### Model Registry and Pricing

The **`VOICE_MODELS`** constant in [`src/voice/voiceCost.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/voice/voiceCost.js) (lines 49-66) defines the available OpenAI Realtime tiers—`standard` and `mini`—along with their USD-per-million-token rates for text, audio, and cached inputs. This registry serves as the authoritative price list for all cost calculations.

### Spend-Guard Limits

The **`VOICE_COST_LIMITS`** object (lines 70-73) establishes two thresholds: `warnUsd` for soft warnings and `capUsd` for hard termination. These limits are passed into every tracker instance and evaluated against the running total after each API response.

### Session Cost Tracker

The **`createVoiceCostTracker`** factory function (lines 124-141) implements a state machine that accumulates usage, latches threshold states, and exposes a snapshot for UI rendering. Each voice session receives its own tracker instance bound to the specific model ID being consumed.

## Token-to-USD Conversion Pipeline

When the Realtime API returns a `response.done` event, the system extracts the `usage` object and processes it through a multi-stage pipeline.

### Splitting Token Categories

The **`splitUsageTokens`** function (lines 248-285) categorizes usage into billable buckets: text versus audio versus image, and cached versus uncached inputs. This granular separation ensures that each token type is priced according to its specific rate from the `VOICE_MODELS` registry.

### Calculating Dollar Amounts

The **`estimateUsageCostUsd`** function (lines 222-236) multiplies each token bucket by its corresponding rate and divides by 1,000,000 to produce the final USD value. This calculation runs for every API response, producing micro-charges that accumulate into the session total.

## Session Lifecycle Integration

Cost tracking begins before the first API call and adapts dynamically as the session configuration resolves.

### Provisional Tracker Creation

When `gevRealtime.start()` initializes a session, it creates a provisional tracker using the tier selected by the user (lines 60-66). This placeholder displays "$0.00" while the application fetches the actual model configuration from the token endpoint.

### Rebinding to the Actual Model

Once the OpenAI token response arrives, the code replaces the provisional tracker with one bound to the real `modelId` (lines 80-87). This defensive step ensures accurate pricing even when environment overrides map tiers to different underlying models than expected.

### Recording Usage Events

Inside `handleRealtimeEvent`, every `response.done` triggers `costTracker.record()` (lines 254-262). This method:

1. Converts the usage object to USD via the pipeline described above.
2. Adds the amount to the running total.
3. Checks against `warnUsd` and `capUsd` thresholds.
4. Returns a state object indicating whether thresholds were crossed.

## Threshold Enforcement and UI Feedback

The tracker communicates session health through a reactive UI binding that updates after every recorded response.

### State Level Transitions

The tracker maintains three levels: `ok`, `warn`, and `cap`. When the running total crosses `warnUsd`, the tracker sets `warned: true` and emits a one-time UI warning. If the total reaches `capUsd`, the tracker sets `capped: true`, marks the session as ending, and triggers automatic termination via `stop()`.

### DOM Synchronization

The **`syncCostUi`** method (implied in the event handling at lines 254-262) writes the formatted cost string (e.g., `~$0.42`) into the `#gev-voice-cost-value` element and updates the `data-level` attribute to enable CSS styling for the current threshold state.

## Error Handling and Edge Cases

The system includes defensive mechanisms for incomplete data and configuration drift.

### Incomplete Session Handling

If a connection closes before the final `response.done` event arrives, the **`markIncomplete()`** method tags the snapshot with an asterisk (e.g., `~$0.42*`) to indicate that the displayed cost may under-represent actual usage.

### Unknown Model Fallback

When the server returns a model ID not present in `VOICE_MODELS`, the code falls back to the most expensive known tier to prevent under-metering (lines 84-95). It simultaneously logs a developer warning to highlight the configuration mismatch.

## Implementation Examples

### Creating a Provisional Tracker

```javascript
// Inside gevRealtime.start() - using selected tier before token fetch
this.costTracker = createVoiceCostTracker({
  tier: this.voiceTier,
  limits: this.voiceLimits,
});

```

### Rebinding After Token Resolution

```javascript
// After token endpoint returns actual model ID
this.costTracker = createVoiceCostTracker({
  modelId: minted.model || resolveVoiceModel(this.voiceTier).id,
  limits: this.voiceLimits,
});

```

### Recording Realtime Usage

```javascript
// Inside handleRealtimeEvent on response.done
const costState = this.costTracker.record(payload.response.usage);

if (costState.warnCrossed) {
  console.warn(`Voice cost warning: ${costState.display}`);
}

if (costState.capCrossed) {
  console.error(`Voice cost cap reached: ${costState.display}`);
  this.stop(); // Force immediate termination
}

```

### Updating the Interface

```javascript
syncCostUi() {
  const state = this.costTracker.state();
  const el = document.getElementById('gev-voice-cost-value');
  
  el.textContent = state.display;    // e.g., "~$0.42"
  el.dataset.level = state.level;    // "ok" | "warn" | "cap"
}

```

## Summary

- **Model registry**: `VOICE_MODELS` in [`voiceCost.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/voiceCost.js) defines OpenAI Realtime rates for standard and mini tiers.
- **Spend guards**: `VOICE_COST_LIMITS` provides configurable `warnUsd` and `capUsd` thresholds.
- **State machine**: `createVoiceCostTracker` accumulates costs, checks limits, and manages UI state transitions.
- **Lifecycle binding**: Trackers start as provisional instances keyed by tier, then rebind to actual `modelId` values after token fetching.
- **Defensive pricing**: Unknown models default to the most expensive tier; incomplete sessions display asterisk-marked estimates.

## Frequently Asked Questions

### How does God’s Eye View prevent unlimited spending during voice sessions?

The **`capUsd`** threshold in `VOICE_COST_LIMITS` acts as a hard ceiling. When `costTracker.record()` detects the running total has reached this limit, it sets `capped: true`, marks the session as ending, and automatically invokes `stop()` to terminate the connection. This mechanism prevents API calls from accumulating beyond the configured maximum.

### What happens if the OpenAI model ID changes mid-session?

When the token endpoint returns a `modelId` that differs from the initial tier selection, [`gevRealtime.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/gevRealtime.js) (lines 80-87) creates a new tracker instance using the actual model ID. This ensures cost calculations use the correct rates from `VOICE_MODELS` rather than the originally requested tier, accounting for environment overrides or server-side model routing.

### How are text and audio tokens priced differently?

The **`splitUsageTokens`** function (lines 248-285) separates usage into distinct categories including text and audio inputs/outputs. The **`estimateUsageCostUsd`** function then applies model-specific rates to each bucket—for example, audio tokens typically cost more than text tokens—before summing the partial costs into the final USD amount for that response.

### What does the asterisk (*) indicate in the cost display?

The asterisk appears when **`markIncomplete()`** has been called, typically because the session disconnected before receiving a final `usage` object. This visual indicator warns users that the displayed dollar amount may be lower than the actual charges incurred, as unreported usage from the final request is not included in the total.