Skip to main content
The weekly command groups your Claude Code usage by week, providing a balanced view between daily granularity and monthly aggregation.

​
Basic Usage

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

​
Command Options

​
Customize Week Start Day

By default, weeks start on Sunday. You can change this with --start-of-week: 
ccusage weekly --start-of-week monday
Available options:
  • sunday (default)
  • monday
  • tuesday
  • wednesday
  • thursday
  • friday
  • saturday

​
Filter by Date Range

Use --since and --until to filter results: 
ccusage weekly --since 20250301 --until 20250331
Dates must be in YYYYMMDD format. The command groups usage into weeks based on the configured start day.

​
Model Breakdown

See per-model costs within each week: 
ccusage weekly --breakdown

​
JSON Output

Export data in JSON format: 
ccusage weekly --json

{
  "weekly": [
    {
      "week": "2025-W10",
      "inputTokens": 285000,
      "outputTokens": 75000,
      "cacheCreationTokens": 22000,
      "cacheReadTokens": 580000,
      "totalTokens": 962000,
      "totalCost": 2.85,
      "modelsUsed": ["claude-sonnet-4-20250514"],
      "modelBreakdowns": [...]
    }
  ],
  "totals": {
    "inputTokens": 285000,
    "outputTokens": 75000,
    "cacheCreationTokens": 22000,
    "cacheReadTokens": 580000,
    "totalTokens": 962000,
    "totalCost": 2.85
  }
}

​
jq Integration

Process JSON output with jq: 
ccusage weekly --jq '.weekly | map({week, cost: .totalCost})'
Weekly reports are ideal for sprint-based workflows. Set --start-of-week to match your team’s sprint start day.

​
Common Flags

​
--start-of-week, -w
enum
Day to start the week on (default: sunday). Options: sunday, monday, tuesday, wednesday, thursday, friday, saturday
​
--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

​
Last 4 Weeks

ccusage weekly --since 20250215 --until 20250314

​
Monday-Starting Weeks

ccusage weekly --start-of-week monday

​
Weekly Sprint Report

ccusage weekly --start-of-week monday --breakdown

​
Weeks Above Budget

ccusage weekly --jq '.weekly[] | select(.totalCost > 5.0)'

​
Understanding Week Format

Weeks are displayed in ISO week format: YYYY-Wxx (e.g., 2025-W10 for the 10th week of 2025). The week number depends on your --start-of-week setting: 
# Default (Sunday start)
ccusage weekly

# ISO standard (Monday start)
ccusage weekly --start-of-week monday

​
Use Cases

​
Sprint-Based Development

Track usage during each development sprint: 
ccusage weekly --start-of-week monday --since 20250303 --until 20250316

​
Weekly Budget Monitoring

Check if weekly costs exceed your budget: 
ccusage weekly --jq '.weekly[] | {week, cost: .totalCost, overBudget: (.totalCost > 10)}'
See which models you’re using each week: 
ccusage weekly --breakdown
Week boundaries depend on your timezone setting. Usage near midnight may be grouped differently based on --timezone.

​
Compact Mode

Weekly reports support compact mode for narrow terminals: 
ccusage weekly --compact
Expand your terminal width to see cache metrics and total tokens.

Build docs developers (and LLMs) love

Get started for freeTalk to us