Implementation:Helicone Helicone GetUsageProcessor

Knowledge Sources	Helicone
Domains	LLM Observability, Cost Calculation, Token Accounting
Last Updated	2026-02-14 00:00 GMT

Overview

Concrete factory function for obtaining a provider-specific usage processor provided by the @helicone/cost package.

Description

getUsageProcessor is a factory function that accepts a ModelProviderName and returns the appropriate IUsageProcessor implementation for that provider, or null if no processor exists. Each returned processor implements the parse method of the IUsageProcessor interface, which takes a ParseInput (containing the response body, optional request body, model name, and streaming flag) and returns a Promise<Result<ModelUsage, string>>.

The factory maps providers to processors as follows:

• OpenAI-compatible (openai, azure, baseten, canopywave, chutes, deepinfra, helicone, mistral, nebius, novita, fireworks, cerebras, perplexity) use OpenAIUsageProcessor
• Anthropic uses AnthropicUsageProcessor
• Groq uses GroqUsageProcessor
• xAI uses XAIUsageProcessor
• OpenRouter uses OpenRouterUsageProcessor
• DeepSeek uses DeepSeekUsageProcessor
• Vertex uses VertexUsageProcessor
• Google AI Studio uses GoogleUsageProcessor
• Bedrock uses BedrockUsageProcessor

Usage

Use this function at the beginning of the cost calculation pipeline to extract normalized token usage from a raw LLM response. The returned processor handles both streaming and non-streaming response bodies.

Code Reference

Source Location

• Repository: Helicone
• File: packages/cost/usage/getUsageProcessor.ts (lines 13-50)
• Interface: packages/cost/usage/IUsageProcessor.ts (lines 1-13)

Signature

// Factory function
function getUsageProcessor(
  provider: ModelProviderName
): IUsageProcessor | null

// Interface returned by the factory
interface IUsageProcessor {
  parse(parseInput: ParseInput): Promise<Result<ModelUsage, string>>;
}

// Input to parse()
interface ParseInput {
  responseBody: string;
  requestBody?: string;
  model: string;
  isStream: boolean;
}

Import

import { getUsageProcessor } from "@helicone/cost";
import type { ModelProviderName, ModelUsage } from "@helicone/cost";

I/O Contract

Inputs

Name	Type	Required	Description
provider	ModelProviderName	Yes	The LLM provider identifier (e.g. "openai", "anthropic", "google-ai-studio", "vertex", "bedrock", "groq", "xai", "openrouter", "deepseek")

Outputs

Name	Type	Description
return	IUsageProcessor ¦ null	A provider-specific usage processor, or null if the provider is not supported

ParseInput Fields

Name	Type	Required	Description
responseBody	string	Yes	The raw JSON response body from the LLM provider
requestBody	string	No	The raw JSON request body (needed by some providers for context)
model	string	Yes	The model identifier, used for format detection (e.g. claude on vertex vs. native vertex)
isStream	boolean	Yes	Whether the response is a streaming response

ModelUsage Output Fields

Name	Type	Description
input	number	Number of prompt/input tokens (excluding cached)
output	number	Number of completion/output tokens
cacheDetails	{ cachedInput: number; write5m?: number; write1h?: number }	Cache-related token counts
thinking	number	Thinking/reasoning tokens (for models that support extended thinking)
image	ModalityUsage	Image token breakdown (input, cachedInput, output)
audio	ModalityUsage	Audio token breakdown
video	ModalityUsage	Video token breakdown
file	ModalityUsage	File token breakdown
web_search	number	Number of web search operations
cost	number	Direct USD cost from provider if reported

Usage Examples

Basic Usage

import { getUsageProcessor } from "@helicone/cost";
import type { ModelProviderName } from "@helicone/cost";

const provider: ModelProviderName = "anthropic";
const processor = getUsageProcessor(provider);

if (processor) {
  const result = await processor.parse({
    responseBody: JSON.stringify(anthropicResponse),
    model: "claude-sonnet-4-20250514",
    isStream: false,
  });

  if (result.data) {
    console.log("Input tokens:", result.data.input);
    console.log("Output tokens:", result.data.output);
    console.log("Cached input:", result.data.cacheDetails?.cachedInput);
  }
}

Streaming Response

const processor = getUsageProcessor("openai");

if (processor) {
  const result = await processor.parse({
    responseBody: rawStreamChunks,
    requestBody: JSON.stringify(originalRequest),
    model: "gpt-4o",
    isStream: true,
  });

  if (result.data) {
    // Use normalized usage for cost calculation
    const usage = result.data;
    console.log(`Tokens: ${usage.input} in / ${usage.output} out`);
  }
}

Related Pages

Implements Principle

• Principle:Helicone_Helicone_Response_Usage_Extraction