Skip to main content
All ccusage commands support the --json flag to output structured JSON data instead of formatted tables. This is useful for integrating ccusage into scripts, dashboards, or other tooling.

​
Basic Usage

ccusage daily --json
ccusage monthly --json
ccusage session --json
ccusage blocks --json

​
Output Structure

​
Daily Report JSON

The daily command outputs an array of daily usage objects: 
type DailyProjectOutput = {
  date: string;                    // Date in YYYY-MM-DD format
  inputTokens: number;             // Total input tokens
  outputTokens: number;            // Total output tokens
  cacheCreationTokens: number;     // Cache creation tokens
  cacheReadTokens: number;         // Cache read tokens
  totalTokens: number;             // Sum of all token types
  totalCost: number;               // Total cost in USD
  modelsUsed: string[];            // Array of model names used
  modelBreakdowns: ModelBreakdown[]; // Per-model cost breakdown
};
​
date
string
required
Date in YYYY-MM-DD format (e.g., “2025-03-04”)
​
inputTokens
number
required
Total number of input tokens processed on this date
​
outputTokens
number
required
Total number of output tokens generated on this date
​
cacheCreationTokens
number
required
Total number of tokens used for creating prompt cache
​
cacheReadTokens
number
required
Total number of tokens read from prompt cache
​
totalTokens
number
required
Sum of all token types (input + output + cacheCreation + cacheRead)
​
totalCost
number
required
Total cost in USD for this date
​
modelsUsed
string[]
required
Array of Claude model names used on this date (e.g., [“claude-sonnet-4-20250514”])
​
modelBreakdowns
ModelBreakdown[]
required
Per-model cost and token breakdown (only included with --breakdown flag)

​
Model Breakdown Structure

type ModelBreakdown = {
  model: string;              // Model name
  inputTokens: number;        // Input tokens for this model
  outputTokens: number;       // Output tokens for this model
  cacheCreationTokens: number; // Cache creation tokens
  cacheReadTokens: number;    // Cache read tokens
  totalCost: number;          // Total cost for this model
};

​
Examples

​
Daily Report with Breakdown

ccusage daily --json --breakdown

​
Date Filtering

ccusage daily --json --since 20250301 --until 20250307

​
Project Grouping

ccusage daily --json --instances

​
Combining with jq

The JSON output works well with jq for filtering and processing: 
# Get total cost across all days
ccusage daily --json | jq '[.[].totalCost] | add'

​
Integration Examples

​
Node.js Script

import { execSync } from 'child_process';

// Get daily usage data
const output = execSync('ccusage daily --json', { encoding: 'utf8' });
const dailyData = JSON.parse(output);

// Calculate total cost
const totalCost = dailyData.reduce((sum, day) => sum + day.totalCost, 0);
console.log(`Total cost: $${totalCost.toFixed(4)}`);

// Find highest usage day
const highestDay = dailyData.reduce((max, day) => 
  day.totalTokens > max.totalTokens ? day : max
);
console.log(`Highest usage: ${highestDay.date} (${highestDay.totalTokens} tokens)`);

​
Python Script

import subprocess
import json

# Get monthly usage data
result = subprocess.run(['ccusage', 'monthly', '--json'], 
                       capture_output=True, text=True)
monthly_data = json.loads(result.stdout)

# Analyze usage trends
for month in monthly_data:
    print(f"{month['month']}: ${month['totalCost']:.4f}")

​
Shell Script Dashboard

#!/bin/bash

# Create a simple usage dashboard
echo "=== Claude Code Usage Dashboard ==="
echo ""

# Today's usage
today=$(date +%Y-%m-%d)
cost=$(ccusage daily --json | jq -r ".[] | select(.date == \"$today\") | .totalCost")
echo "Today's cost: \$$cost"

# This month's total
month_cost=$(ccusage monthly --json | jq -r '.[0].totalCost')
echo "This month: \$$month_cost"

# Most used model
model=$(ccusage daily --json | jq -r '[.[].modelsUsed[]] | group_by(.) | max_by(length) | .[0]')
echo "Most used model: $model"
JSON output is sent to stdout, while any warnings or errors go to stderr. This allows you to pipe JSON data while still seeing diagnostic messages.
When using --instances flag, the output structure changes from an array to an object with project names as keys. Make sure your scripts handle both formats appropriately.

​
Type Definitions

The complete TypeScript type definitions are available in the source: 
// From src/_json-output-types.ts
import type { DailyDate, ModelName } from './_types';
import type { ModelBreakdown } from './data-loader';

export type DailyProjectOutput = {
  date: DailyDate;
  inputTokens: number;
  outputTokens: number;
  cacheCreationTokens: number;
  cacheReadTokens: number;
  totalTokens: number;
  totalCost: number;
  modelsUsed: ModelName[];
  modelBreakdowns: ModelBreakdown[];
};
See Library Usage for importing these types in your own TypeScript projects.

Build docs developers (and LLMs) love

Get started for freeTalk to us