Skip to main content

​
Overview

The calculate-cost module provides functions for calculating costs and aggregating token usage across different time periods and models. It handles both pre-calculated costs and dynamic cost calculations based on model pricing.

​
Functions

​
calculateTotals()

Calculates total token usage and cost across multiple usage data entries. 
export function calculateTotals(
  data: Array<DailyUsage | MonthlyUsage | WeeklyUsage | SessionUsage>
): TokenTotals
​
data
Array<DailyUsage | MonthlyUsage | WeeklyUsage | SessionUsage>
required
Array of usage data from any aggregation period
​
returns
TokenTotals
Aggregated token counts and total cost
TokenTotals Type:
​
inputTokens
number
Total input tokens
​
outputTokens
number
Total output tokens
​
cacheCreationTokens
number
Total cache creation tokens
​
cacheReadTokens
number
Total cache read tokens
​
totalCost
number
Total cost in USD
import { loadDailyUsageData } from 'ccusage/data-loader';
import { calculateTotals } from 'ccusage/calculate-cost';

const dailyData = await loadDailyUsageData({
  since: '20240101',
  until: '20240131'
});

const totals = calculateTotals(dailyData);

console.log('January 2024 Totals:');
console.log(`  Input Tokens: ${totals.inputTokens.toLocaleString()}`);
console.log(`  Output Tokens: ${totals.outputTokens.toLocaleString()}`);
console.log(`  Cache Creation: ${totals.cacheCreationTokens.toLocaleString()}`);
console.log(`  Cache Read: ${totals.cacheReadTokens.toLocaleString()}`);
console.log(`  Total Cost: $${totals.totalCost.toFixed(2)}`);

​
getTotalTokens()

Calculates the sum of all token types (input, output, cache creation, cache read). 
export function getTotalTokens(
  tokens: AggregatedTokenCounts
): number
​
tokens
AggregatedTokenCounts
required
Token counts object
​
returns
number
Sum of all token types
AggregatedTokenCounts Type:
​
inputTokens
number
Input token count
​
outputTokens
number
Output token count
​
cacheCreationTokens
number
Cache creation token count
​
cacheReadTokens
number
Cache read token count
import { getTotalTokens } from 'ccusage/calculate-cost';

const tokens = {
  inputTokens: 1000,
  outputTokens: 500,
  cacheCreationTokens: 200,
  cacheReadTokens: 100
};

const total = getTotalTokens(tokens);
console.log(`Total tokens: ${total}`); // 1800

​
createTotalsObject()

Creates a complete totals object by adding total token count to existing totals. 
export function createTotalsObject(
  totals: TokenTotals
): TotalsObject
​
totals
TokenTotals
required
Token totals with cost information
​
returns
TotalsObject
Complete totals object including total token sum
TotalsObject Type:
​
inputTokens
number
Total input tokens
​
outputTokens
number
Total output tokens
​
cacheCreationTokens
number
Total cache creation tokens
​
cacheReadTokens
number
Total cache read tokens
​
totalCost
number
Total cost in USD
​
totalTokens
number
Sum of all token types
import { loadDailyUsageData } from 'ccusage/data-loader';
import { calculateTotals, createTotalsObject } from 'ccusage/calculate-cost';

const dailyData = await loadDailyUsageData();
const totals = calculateTotals(dailyData);
const totalsObject = createTotalsObject(totals);

console.log('Complete Totals:');
console.log(`  Input: ${totalsObject.inputTokens.toLocaleString()}`);
console.log(`  Output: ${totalsObject.outputTokens.toLocaleString()}`);
console.log(`  Cache Creation: ${totalsObject.cacheCreationTokens.toLocaleString()}`);
console.log(`  Cache Read: ${totalsObject.cacheReadTokens.toLocaleString()}`);
console.log(`  Total Tokens: ${totalsObject.totalTokens.toLocaleString()}`);
console.log(`  Cost: $${totalsObject.totalCost.toFixed(4)}`);

​
Usage Patterns

​
Analyzing Token Distribution

import { loadDailyUsageData } from 'ccusage/data-loader';
import { calculateTotals, getTotalTokens } from 'ccusage/calculate-cost';

const dailyData = await loadDailyUsageData();
const totals = calculateTotals(dailyData);
const totalTokens = getTotalTokens(totals);

// Calculate percentages
const distribution = {
  input: (totals.inputTokens / totalTokens) * 100,
  output: (totals.outputTokens / totalTokens) * 100,
  cacheCreation: (totals.cacheCreationTokens / totalTokens) * 100,
  cacheRead: (totals.cacheReadTokens / totalTokens) * 100
};

console.log('Token Distribution:');
console.log(`  Input: ${distribution.input.toFixed(2)}%`);
console.log(`  Output: ${distribution.output.toFixed(2)}%`);
console.log(`  Cache Creation: ${distribution.cacheCreation.toFixed(2)}%`);
console.log(`  Cache Read: ${distribution.cacheRead.toFixed(2)}%`);

​
Comparing Time Periods

import { loadMonthlyUsageData } from 'ccusage/data-loader';
import { calculateTotals } from 'ccusage/calculate-cost';

const monthlyData = await loadMonthlyUsageData({
  order: 'desc'
});

if (monthlyData.length >= 2) {
  const [currentMonth, previousMonth] = monthlyData;
  
  const currentTotals = calculateTotals([currentMonth]);
  const previousTotals = calculateTotals([previousMonth]);
  
  const costChange = currentTotals.totalCost - previousTotals.totalCost;
  const percentChange = (costChange / previousTotals.totalCost) * 100;
  
  console.log(`${currentMonth.month} vs ${previousMonth.month}:`);
  console.log(`  Current: $${currentTotals.totalCost.toFixed(2)}`);
  console.log(`  Previous: $${previousTotals.totalCost.toFixed(2)}`);
  console.log(`  Change: ${percentChange > 0 ? '+' : ''}${percentChange.toFixed(2)}%`);
}

​
Project Cost Tracking

import { loadDailyUsageData } from 'ccusage/data-loader';
import { calculateTotals } from 'ccusage/calculate-cost';

const projects = ['project-a', 'project-b', 'project-c'];

for (const project of projects) {
  const data = await loadDailyUsageData({
    project,
    groupByProject: true
  });
  
  const totals = calculateTotals(data);
  
  console.log(`Project: ${project}`);
  console.log(`  Total Cost: $${totals.totalCost.toFixed(2)}`);
  console.log(`  Days Active: ${data.length}`);
  console.log(`  Avg Cost/Day: $${(totals.totalCost / data.length).toFixed(2)}`);
  console.log('');
}

​
Cost Breakdown by Model

import { loadDailyUsageData } from 'ccusage/data-loader';
import { calculateTotals } from 'ccusage/calculate-cost';

const dailyData = await loadDailyUsageData();
const totals = calculateTotals(dailyData);

// Aggregate model breakdowns
const modelCosts = new Map<string, number>();

for (const day of dailyData) {
  for (const breakdown of day.modelBreakdowns) {
    const current = modelCosts.get(breakdown.modelName) || 0;
    modelCosts.set(breakdown.modelName, current + breakdown.cost);
  }
}

console.log('Cost by Model:');
for (const [model, cost] of Array.from(modelCosts).sort((a, b) => b[1] - a[1])) {
  const percentage = (cost / totals.totalCost) * 100;
  console.log(`  ${model}: $${cost.toFixed(4)} (${percentage.toFixed(2)}%)`);
}

​
Types

​
TokenTotals

Token totals including cost information. 
type TokenTotals = {
  inputTokens: number;
  outputTokens: number;
  cacheCreationTokens: number;
  cacheReadTokens: number;
  totalCost: number;
};

​
TotalsObject

Complete totals object with token counts, cost, and total token sum. 
type TotalsObject = TokenTotals & {
  totalTokens: number;
};

​
AggregatedTokenCounts

Token counts object for aggregation. 
type AggregatedTokenCounts = {
  inputTokens: number;
  outputTokens: number;
  cacheCreationTokens: number;
  cacheReadTokens: number;
};

​
Integration with Data Loader

The calculate-cost module works seamlessly with all data loader functions: 
import { loadDailyUsageData } from 'ccusage/data-loader';
import { calculateTotals } from 'ccusage/calculate-cost';

const daily = await loadDailyUsageData();
const totals = calculateTotals(daily);

Build docs developers (and LLMs) love

Get started for freeTalk to us