npx ccusage

Fork 0

ccusage docs guide json-output.md

16 kB

Markdown

at main

Ben Vargas · feat(unified): --sections and --by-agent for single-invocation reporting (#1396) · 3mo ago

e2e0c5ed

JSON Output #

ccusage supports structured JSON output for all report types, making it easy to integrate with other tools, scripts, or applications that need to process usage data programmatically.

Enabling JSON Output #

Add the --json (or -j) flag to any command:

# Daily report in JSON format
ccusage daily --json

# Monthly report in JSON format
ccusage monthly --json

# Session report in JSON format
ccusage session --json

# 5-hour blocks report in JSON format
ccusage blocks --json

Use --no-cost with --json when reports should omit cost data:

ccusage daily --json --no-cost
ccusage blocks --json --no-cost

This removes cost fields such as totalCost, costUSD, and nested cost values while keeping token, model, date, block, burn-rate, and projection fields.

Unified reports also support JSON-oriented flags for dashboard-style consumers:

ccusage daily --sections daily,monthly,session --by-agent --json

--sections emits each requested unified section from one load. The invoked command's section is always included, and the top-level totals object remains the total for that invoked section. JSON keys are emitted with the invoked section first, then remaining sections in daily, weekly, monthly, session order, with totals last. --by-agent adds an agents array to daily, weekly, and monthly rows; session rows are already per-agent.

{
	"daily": [
		{
			"agent": "all",
			"agents": [
				{
					"agent": "claude",
					"cacheCreationTokens": 20,
					"cacheReadTokens": 30,
					"inputTokens": 500,
					"modelBreakdowns": [
						{
							"cacheCreationTokens": 20,
							"cacheReadTokens": 30,
							"cost": 0.02,
							"inputTokens": 500,
							"modelName": "claude-sonnet-4-20250514",
							"outputTokens": 100
						}
					],
					"modelsUsed": ["claude-sonnet-4-20250514"],
					"outputTokens": 100,
					"totalCost": 0.02,
					"totalTokens": 650
				},
				{
					"agent": "codex",
					"cacheCreationTokens": 0,
					"cacheReadTokens": 100,
					"inputTokens": 900,
					"modelBreakdowns": [
						{
							"cacheCreationTokens": 0,
							"cacheReadTokens": 100,
							"cost": 0.0031375,
							"inputTokens": 900,
							"modelName": "gpt-5",
							"outputTokens": 200
						}
					],
					"modelsUsed": ["gpt-5"],
					"outputTokens": 200,
					"totalCost": 0.0031375,
					"totalTokens": 1200
				}
			],
			"cacheCreationTokens": 20,
			"cacheReadTokens": 130,
			"inputTokens": 1400,
			"metadata": {
				"agents": ["claude", "codex"]
			},
			"modelBreakdowns": [
				{
					"cacheCreationTokens": 20,
					"cacheReadTokens": 30,
					"cost": 0.02,
					"inputTokens": 500,
					"modelName": "claude-sonnet-4-20250514",
					"outputTokens": 100
				},
				{
					"cacheCreationTokens": 0,
					"cacheReadTokens": 100,
					"cost": 0.0031375,
					"inputTokens": 900,
					"modelName": "gpt-5",
					"outputTokens": 200
				}
			],
			"modelsUsed": ["claude-sonnet-4-20250514", "gpt-5"],
			"outputTokens": 300,
			"period": "2026-01-02",
			"totalCost": 0.023137500000000002,
			"totalTokens": 1850
		}
	],
	"monthly": [
		{
			"agent": "all",
			"agents": [
				{
					"agent": "claude",
					"cacheCreationTokens": 20,
					"cacheReadTokens": 30,
					"inputTokens": 500,
					"modelBreakdowns": [
						{
							"cacheCreationTokens": 20,
							"cacheReadTokens": 30,
							"cost": 0.02,
							"inputTokens": 500,
							"modelName": "claude-sonnet-4-20250514",
							"outputTokens": 100
						}
					],
					"modelsUsed": ["claude-sonnet-4-20250514"],
					"outputTokens": 100,
					"totalCost": 0.02,
					"totalTokens": 650
				},
				{
					"agent": "codex",
					"cacheCreationTokens": 0,
					"cacheReadTokens": 100,
					"inputTokens": 900,
					"modelBreakdowns": [
						{
							"cacheCreationTokens": 0,
							"cacheReadTokens": 100,
							"cost": 0.0031375,
							"inputTokens": 900,
							"modelName": "gpt-5",
							"outputTokens": 200
						}
					],
					"modelsUsed": ["gpt-5"],
					"outputTokens": 200,
					"totalCost": 0.0031375,
					"totalTokens": 1200
				}
			],
			"cacheCreationTokens": 20,
			"cacheReadTokens": 130,
			"inputTokens": 1400,
			"metadata": {
				"agents": ["claude", "codex"]
			},
			"modelBreakdowns": [
				{
					"cacheCreationTokens": 20,
					"cacheReadTokens": 30,
					"cost": 0.02,
					"inputTokens": 500,
					"modelName": "claude-sonnet-4-20250514",
					"outputTokens": 100
				},
				{
					"cacheCreationTokens": 0,
					"cacheReadTokens": 100,
					"cost": 0.0031375,
					"inputTokens": 900,
					"modelName": "gpt-5",
					"outputTokens": 200
				}
			],
			"modelsUsed": ["claude-sonnet-4-20250514", "gpt-5"],
			"outputTokens": 300,
			"period": "2026-01",
			"totalCost": 0.023137500000000002,
			"totalTokens": 1850
		}
	],
	"session": [
		{
			"agent": "claude",
			"cacheCreationTokens": 20,
			"cacheReadTokens": 30,
			"inputTokens": 500,
			"metadata": {
				"lastActivity": "2026-01-02T10:00:00.000Z"
			},
			"modelBreakdowns": [
				{
					"cacheCreationTokens": 20,
					"cacheReadTokens": 30,
					"cost": 0.02,
					"inputTokens": 500,
					"modelName": "claude-sonnet-4-20250514",
					"outputTokens": 100
				}
			],
			"modelsUsed": ["claude-sonnet-4-20250514"],
			"outputTokens": 100,
			"period": "claude-session",
			"totalCost": 0.02,
			"totalTokens": 650
		},
		{
			"agent": "codex",
			"cacheCreationTokens": 0,
			"cacheReadTokens": 100,
			"inputTokens": 900,
			"metadata": {
				"lastActivity": "2026-01-02T11:00:00.000Z",
				"reasoningOutputTokens": 20
			},
			"modelBreakdowns": [
				{
					"cacheCreationTokens": 0,
					"cacheReadTokens": 100,
					"cost": 0.0031375,
					"inputTokens": 900,
					"modelName": "gpt-5",
					"outputTokens": 200
				}
			],
			"modelsUsed": ["gpt-5"],
			"outputTokens": 200,
			"period": "codex-session",
			"totalCost": 0.0031375,
			"totalTokens": 1200
		}
	],
	"totals": {
		"cacheCreationTokens": 20,
		"cacheReadTokens": 130,
		"inputTokens": 1400,
		"outputTokens": 300,
		"totalCost": 0.023137500000000002,
		"totalTokens": 1850
	}
}

JSON Structure #

Daily Reports (Standard) #

Standard daily reports aggregate usage across all projects:

{
	"daily": [
		{
			"date": "2026-05-16",
			"inputTokens": 277,
			"outputTokens": 31456,
			"cacheCreationTokens": 512,
			"cacheReadTokens": 1024,
			"totalTokens": 33269,
			"totalCost": 17.58,
			"modelsUsed": ["claude-opus-4-1-20250805", "claude-sonnet-4-5-20250929"],
			"modelBreakdowns": [...]
		}
	],
	"totals": {
		"inputTokens": 11174,
		"outputTokens": 720366,
		"cacheCreationTokens": 896,
		"cacheReadTokens": 2304,
		"totalTokens": 734740,
		"totalCost": 336.47
	}
}

Daily Reports (Project-Grouped) #

When using --instances, daily reports group usage by project:

{
	"projects": {
		"my-frontend-app": [
			{
				"date": "2026-05-16",
				"inputTokens": 177,
				"outputTokens": 16456,
				"cacheCreationTokens": 256,
				"cacheReadTokens": 512,
				"totalTokens": 17401,
				"totalCost": 7.33,
				"modelsUsed": ["claude-sonnet-4-5-20250929"],
				"modelBreakdowns": [...]
			}
		],
		"backend-api": [
			{
				"date": "2026-05-16",
				"inputTokens": 100,
				"outputTokens": 15000,
				"cacheCreationTokens": 256,
				"cacheReadTokens": 512,
				"totalTokens": 15868,
				"totalCost": 10.25,
				"modelsUsed": ["claude-opus-4-1-20250805"],
				"modelBreakdowns": [...]
			}
		]
	},
	"totals": {
		"inputTokens": 277,
		"outputTokens": 31456,
		"cacheCreationTokens": 512,
		"cacheReadTokens": 1024,
		"totalTokens": 33269,
		"totalCost": 17.58
	}
}

Usage #

# Standard aggregated output
ccusage daily --json

# Project-grouped output
ccusage daily --instances --json

# Filter to specific project
ccusage daily --project my-frontend-app --json

Monthly Reports #

{
	"type": "monthly",
	"data": [
		{
			"month": "2026-04",
			"models": ["claude-opus-4-1-20250805", "claude-sonnet-4-5-20250929"],
			"inputTokens": 11174,
			"outputTokens": 720366,
			"cacheCreationTokens": 896,
			"cacheReadTokens": 2304,
			"totalTokens": 734740,
			"costUSD": 336.47
		}
	],
	"summary": {
		"totalInputTokens": 11174,
		"totalOutputTokens": 720366,
		"totalCacheCreationTokens": 896,
		"totalCacheReadTokens": 2304,
		"totalTokens": 734740,
		"totalCostUSD": 336.47
	}
}

Session Reports #

{
	"type": "session",
	"data": [
		{
			"session": "session-1",
			"models": ["claude-opus-4-1-20250805", "claude-sonnet-4-5-20250929"],
			"inputTokens": 4512,
			"outputTokens": 350846,
			"cacheCreationTokens": 512,
			"cacheReadTokens": 1024,
			"totalTokens": 356894,
			"costUSD": 156.4,
			"firstActivity": "2026-05-15T09:30:00.000Z",
			"lastActivity": "2026-05-15T17:45:30.000Z"
		}
	],
	"summary": {
		"totalInputTokens": 11174,
		"totalOutputTokens": 720445,
		"totalCacheCreationTokens": 768,
		"totalCacheReadTokens": 1792,
		"totalTokens": 734179,
		"totalCostUSD": 336.68
	}
}

Blocks Reports #

{
	"type": "blocks",
	"data": [
		{
			"blockStart": "2026-05-16T10:00:00.000Z",
			"blockEnd": "2026-05-16T15:00:00.000Z",
			"isActive": true,
			"timeRemaining": "2h 15m",
			"models": ["claude-sonnet-4-5-20250929"],
			"inputTokens": 1250,
			"outputTokens": 15000,
			"cacheCreationTokens": 256,
			"cacheReadTokens": 512,
			"totalTokens": 17018,
			"costUSD": 8.75,
			"burnRate": 2400,
			"projectedTotal": 25000,
			"projectedCost": 12.5
		}
	],
	"summary": {
		"totalInputTokens": 11174,
		"totalOutputTokens": 720366,
		"totalCacheCreationTokens": 896,
		"totalCacheReadTokens": 2304,
		"totalTokens": 734740,
		"totalCostUSD": 336.47
	}
}

Field Descriptions #

Common Fields #

models: Array of Claude model names used
inputTokens: Number of input tokens consumed
outputTokens: Number of output tokens generated
cacheCreationTokens: Tokens used for cache creation
cacheReadTokens: Tokens read from cache
totalTokens: Sum of all token types
costUSD: Estimated cost in US dollars

Report-Specific Fields #

Daily Reports #

date: Date in YYYY-MM-DD format

Monthly Reports #

month: Month in YYYY-MM format

Session Reports #

session: Session identifier
firstActivity: RFC 3339 timestamp of first activity in the session
lastActivity: RFC 3339 timestamp of last activity in the session

Blocks Reports #

blockStart: ISO timestamp of block start
blockEnd: ISO timestamp of block end
isActive: Whether the block is currently active
timeRemaining: Human-readable time remaining (active blocks only)
burnRate: Tokens per hour rate (active blocks only)
projectedTotal: Projected total tokens for the block
projectedCost: Projected total cost for the block

Filtering with JSON Output #

All filtering options work with JSON output:

# Filter by date range
ccusage daily --json --since 20260510 --until 20260516

# Different cost calculation modes
ccusage monthly --json --mode calculate
ccusage session --json --mode display

# Sort order
ccusage daily --json --order asc

# With model breakdown
ccusage daily --json --breakdown

# Hide cost fields
ccusage daily --json --no-cost

# Project analysis
ccusage daily --json --instances                    # Group by project
ccusage daily --json --project my-project           # Filter to project
ccusage daily --json --instances --project my-app   # Combined usage

Model Breakdown JSON #

When using --breakdown, the JSON includes per-model details:

{
	"type": "daily",
	"data": [
		{
			"date": "2026-05-16",
			"models": ["claude-opus-4-1-20250805", "claude-sonnet-4-5-20250929"],
			"inputTokens": 277,
			"outputTokens": 31456,
			"totalTokens": 33269,
			"costUSD": 17.58,
			"breakdown": {
				"claude-opus-4-1-20250805": {
					"inputTokens": 100,
					"outputTokens": 15000,
					"cacheCreationTokens": 256,
					"cacheReadTokens": 512,
					"totalTokens": 15868,
					"costUSD": 10.25
				},
				"claude-sonnet-4-5-20250929": {
					"inputTokens": 177,
					"outputTokens": 16456,
					"cacheCreationTokens": 256,
					"cacheReadTokens": 512,
					"totalTokens": 17401,
					"costUSD": 7.33
				}
			}
		}
	]
}

Integration Examples #

Using with jq #

You can pipe JSON output to jq for advanced filtering and formatting:

# Get total cost for the last 7 days
ccusage daily --json --since $(date -d '7 days ago' +%Y%m%d) | jq '.summary.totalCostUSD'

# List all unique models used
ccusage session --json | jq -r '.data[].models[]' | sort -u

# Find the most expensive session
ccusage session --json | jq -r '.data | sort_by(.costUSD) | reverse | .[0].session'

# Get daily costs as CSV
ccusage daily --json | jq -r '.daily[] | [.date, .totalCost] | @csv'

# Analyze project costs
ccusage daily --instances --json | jq -r '.projects | to_entries[] | [.key, (.value | map(.totalCost) | add)] | @csv'

# Find most expensive project
ccusage daily --instances --json | jq -r '.projects | to_entries | map({project: .key, total: (.value | map(.totalCost) | add)}) | sort_by(.total) | reverse | .[0].project'

# Get usage by project for specific date
ccusage daily --instances --json | jq '.projects | to_entries[] | select(.value[].date == "2026-05-16") | {project: .key, usage: .value[0]}'

Using with Python #

import json
import subprocess

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

# Process the data
for day in data['data']:
    print(f"Date: {day['date']}, Cost: ${day['costUSD']:.2f}")

total_cost = data['totals']['totalCost']
print(f"Total cost: ${total_cost:.2f}")

# Project analysis example
result = subprocess.run(['ccusage', 'daily', '--instances', '--json'], capture_output=True, text=True)
project_data = json.loads(result.stdout)

if 'projects' in project_data:
    for project_name, daily_entries in project_data['projects'].items():
        project_total = sum(day['totalCost'] for day in daily_entries)
        print(f"Project {project_name}: ${project_total:.2f}")

    # Find highest spending project
    project_totals = {
        project: sum(day['totalCost'] for day in days)
        for project, days in project_data['projects'].items()
    }
    top_project = max(project_totals, key=project_totals.get)
    print(f"Highest spending project: {top_project} (${project_totals[top_project]:.2f})")

Using with Node.js #

import { execSync } from 'node:child_process';

// Get session usage data
const output = execSync('ccusage session --json', { encoding: 'utf-8' });
const data = JSON.parse(output);

// Find sessions over $10
const expensiveSessions = data.data.filter((session) => session.costUSD > 10);
console.log(`Found ${expensiveSessions.length} expensive sessions`);

expensiveSessions.forEach((session) => {
	console.log(`${session.session}: $${session.costUSD.toFixed(2)}`);
});

// Project analysis example
const projectOutput = execSync('ccusage daily --instances --json', { encoding: 'utf-8' });
const projectData = JSON.parse(projectOutput);

if (projectData.projects) {
	// Calculate total cost per project
	const projectCosts = Object.entries(projectData.projects).map(([name, days]) => ({
		name,
		totalCost: days.reduce((sum, day) => sum + day.totalCost, 0),
		totalTokens: days.reduce((sum, day) => sum + day.totalTokens, 0),
	}));

	// Sort by cost descending
	projectCosts.sort((a, b) => b.totalCost - a.totalCost);

	console.log('Project Usage Summary:');
	projectCosts.forEach((project) => {
		console.log(
			`${project.name}: $${project.totalCost.toFixed(2)} (${project.totalTokens.toLocaleString()} tokens)`,
		);
	});
}

Programmatic Usage #

JSON output is designed for programmatic consumption:

Consistent structure: All fields are always present (with 0 or empty values when not applicable)
Standard types: Numbers for metrics, strings for identifiers, arrays for lists
ISO timestamps: Standardized date/time formats for reliable parsing
Stable schema: Field names and structures remain consistent across versions