Skip to main content
The monthly command aggregates your Claude Code usage by month, providing a high-level view of your token consumption and costs over extended periods.

​
Basic Usage

ccusage monthly
This displays a table showing your usage for each month, including:
  • Input and output tokens
  • Cache creation and read tokens
  • Total tokens consumed
  • Total cost in USD
  • Models used

​
Command Options

​
Filter by Date Range

Use --since and --until to filter results to a specific date range: 
ccusage monthly --since 20250101 --until 20250331
Dates must be in YYYYMMDD format. For monthly reports, you typically use the first day of months (e.g., 20250101 for January 2025).

​
Model Breakdown

See per-model costs within each month: 
ccusage monthly --breakdown
This shows detailed token usage and costs for each model used during the month.

​
JSON Output

Export data in JSON format: 
ccusage monthly --json

{
  "monthly": [
    {
      "month": "202503",
      "inputTokens": 1250000,
      "outputTokens": 340000,
      "cacheCreationTokens": 89000,
      "cacheReadTokens": 2500000,
      "totalTokens": 4179000,
      "totalCost": 12.45,
      "modelsUsed": [
        "claude-sonnet-4-20250514",
        "claude-opus-4-20250514"
      ],
      "modelBreakdowns": [...]
    }
  ],
  "totals": {
    "inputTokens": 1250000,
    "outputTokens": 340000,
    "cacheCreationTokens": 89000,
    "cacheReadTokens": 2500000,
    "totalTokens": 4179000,
    "totalCost": 12.45
  }
}

​
jq Integration

Process JSON output with jq for advanced analysis: 
ccusage monthly --jq '.monthly | map({month, cost: .totalCost}) | sort_by(.cost) | reverse'
Monthly reports are perfect for tracking costs over quarters or entire years. Combine with jq to create custom reports.

​
Common Flags

​
--since, -s
string
Filter from date (YYYYMMDD format)
​
--until, -u
string
Filter until date (YYYYMMDD format)
​
--breakdown, -b
boolean
Show per-model cost breakdown (default: false)
​
--json, -j
boolean
Output in JSON format (default: false)
​
--jq, -q
string
Process JSON output with jq command (requires jq binary, implies —json)
​
--mode, -m
enum
Cost calculation mode: auto (use pre-calculated if available), calculate (always calculate from tokens), display (always use pre-calculated)
​
--timezone, -z
string
Timezone for date grouping (e.g., UTC, America/New_York, Asia/Tokyo). Default: system timezone
​
--locale, -l
string
Locale for date/time formatting (e.g., en-US, ja-JP, de-DE). Default: en-US
​
--compact
boolean
Force compact mode for narrow displays
​
--offline, -O
boolean
Use cached pricing data instead of fetching from API (default: false)
​
--debug, -d
boolean
Show pricing mismatch information for debugging (default: false)

​
Examples

​
First Quarter 2025

ccusage monthly --since 20250101 --until 20250331

​
Full Year with Model Breakdown

ccusage monthly --since 20250101 --until 20251231 --breakdown

​
Top 3 Most Expensive Months

ccusage monthly --jq '.monthly | sort_by(.totalCost) | reverse | .[0:3]'

​
Export to CSV

ccusage monthly --jq -r '.monthly[] | [.month, .totalCost] | @csv' > monthly-costs.csv

​
Understanding Monthly Aggregation

​
Month Format

Months are displayed in YYYYMM format (e.g., 202503 for March 2025).

​
Timezone Considerations

Monthly aggregation respects the --timezone flag. Usage is grouped by month in the specified timezone: 
ccusage monthly --timezone America/New_York
This can affect which month usage is attributed to if you work across midnight in different timezones.

​
Model Usage

The modelsUsed array shows all models used during the month. Use --breakdown to see per-model costs: 
ccusage monthly --breakdown

​
Use Cases

​
Budget Tracking

Monitor monthly spending to stay within budget: 
ccusage monthly --jq '.monthly[] | select(.totalCost > 50) | {month, totalCost}'
Identify usage patterns over time: 
ccusage monthly --json > monthly-usage.json

​
Model Adoption

Track which models you’re using each month: 
ccusage monthly --breakdown
Monthly reports aggregate all usage data, which can be slow for large datasets. Consider using date filters to limit the range.

​
Compact Mode

Like daily reports, monthly reports support compact mode for narrow terminals: 
ccusage monthly --compact
When in compact mode, cache metrics and total tokens are hidden. Expand your terminal width to see all columns.

Build docs developers (and LLMs) love

Get started for freeTalk to us