Weekly Reports

Weekly reports aggregate your Claude Code usage by week, providing a mid-range view between daily and monthly reports. This helps identify weekly patterns and trends in your usage.

Basic Usage

Show all weekly usage:

ccusage weekly

Example Output

┌────────────────┬──────────────────┬────────┬─────────┬─────────────┬────────────┬──────────────┬────────────┐
│ Week           │ Models           │ Input  │ Output  │ Cache Create│ Cache Read │ Total Tokens │ Cost (USD) │
├────────────────┼──────────────────┼────────┼─────────┼─────────────┼────────────┼──────────────┼────────────┤
│ 2025-06-16     │ • opus-4         │  1,234 │ 156,789 │       2,048 │      4,096 │      164,167 │     $87.56 │
│                │ • sonnet-4       │        │         │             │            │              │            │
├────────────────┼──────────────────┼────────┼─────────┼─────────────┼────────────┼──────────────┼────────────┤
│ 2025-06-23     │ • sonnet-4       │  2,456 │ 234,567 │       3,072 │      6,144 │      246,239 │    $104.33 │
├────────────────┼──────────────────┼────────┼─────────┼─────────────┼────────────┼──────────────┼────────────┤
│ 2025-06-30     │ • opus-4         │  3,789 │ 345,678 │       4,096 │      8,192 │      361,755 │    $156.78 │
│                │ • sonnet-4       │        │         │             │            │              │            │
└────────────────┴──────────────────┴────────┴─────────┴─────────────┴────────────┴──────────────┴────────────┘

Understanding the Columns

The columns are identical to daily reports but aggregated by week:

• Week: Start date of the week (configurable)
• Models: All Claude models used during the week
• Input/Output: Total tokens for the week
• Cache Create/Read: Cache token usage
• Total Tokens: Sum of all token types
• Cost (USD): Estimated cost for the week

Command Options

Week Start Day

Configure which day starts the week:

# Start week on Sunday (default)
ccusage weekly --start-of-week sunday

# Start week on Monday
ccusage weekly --start-of-week monday
ccusage weekly -w monday

# Other options: tuesday, wednesday, thursday, friday, saturday

Date Filtering

Filter by date range:

# Show specific period
ccusage weekly --since 20250601 --until 20250630

# Show last 4 weeks
ccusage weekly --since 20250501

Sort Order

Control the order of weeks:

# Newest weeks first (default)
ccusage weekly --order desc

# Oldest weeks first
ccusage weekly --order asc

Model Breakdown

See per-model weekly costs:

ccusage weekly --breakdown

┌────────────────┬──────────────────┬────────┬─────────┬────────────┐
│ Week           │ Models           │ Input  │ Output  │ Cost (USD) │
├────────────────┼──────────────────┼────────┼─────────┼────────────┤
│ 2025-06-16     │ opus-4, sonnet-4 │  1,234 │ 156,789 │     $87.56 │
├────────────────┼──────────────────┼────────┼─────────┼────────────┤
│   └─ opus-4    │                  │    800 │  80,000 │     $54.80 │
├────────────────┼──────────────────┼────────┼─────────┼────────────┤
│   └─ sonnet-4  │                  │    434 │  76,789 │     $32.76 │
└────────────────┴──────────────────┴────────┴─────────┴────────────┘

JSON Output

Export weekly data as JSON:

ccusage weekly --json

{
  "weekly": [
    {
      "week": "2025-06-16",
      "inputTokens": 1234,
      "outputTokens": 156789,
      "cacheCreationTokens": 2048,
      "cacheReadTokens": 4096,
      "totalTokens": 164167,
      "totalCost": 87.56,
      "modelsUsed": ["claude-opus-4-20250514", "claude-sonnet-4-20250514"],
      "modelBreakdowns": {
        "claude-opus-4-20250514": {
          "inputTokens": 800,
          "outputTokens": 80000,
          "totalCost": 54.80
        },
        "claude-sonnet-4-20250514": {
          "inputTokens": 434,
          "outputTokens": 76789,
          "totalCost": 32.76
        }
      }
    }
  ],
  "totals": {
    "inputTokens": 7479,
    "outputTokens": 737034,
    "cacheCreationTokens": 9216,
    "cacheReadTokens": 18432,
    "totalTokens": 772161,
    "totalCost": 348.67
  }
}

Project Analysis

Group weekly usage by project:

# Show weekly usage per project
ccusage weekly --instances

# Filter to specific project
ccusage weekly --project my-project

Cost Calculation Modes

Control cost calculation:

# Auto mode (default)
ccusage weekly --mode auto

# Always calculate from tokens
ccusage weekly --mode calculate

# Only use pre-calculated costs
ccusage weekly --mode display

Offline Mode

Use cached pricing data:

ccusage weekly --offline

Common Use Cases

Weekly Trends

# See usage trends over past months
ccusage weekly --since 20250401

Sprint Analysis

# Track usage during 2-week sprints (Monday start)
ccusage weekly --start-of-week monday --since 20250601

Budget Planning

# Export for weekly budget tracking
ccusage weekly --json > weekly-budget.json

Compare Workweeks

# Monday-Friday work pattern analysis
ccusage weekly --start-of-week monday --breakdown

Team Reporting

# Weekly team usage report
ccusage weekly --instances --start-of-week monday

Tips

1. Week Start: Choose a start day that aligns with your work schedule
2. Breakdown View: Use --breakdown to identify which models drive costs
3. JSON Export: Weekly JSON data is perfect for creating trend charts
4. Project Tracking: Use --instances to track project-specific weekly usage

Related Commands

• Daily Reports - Day-by-day analysis
• Monthly Reports - Monthly aggregates
• Session Reports - Per-conversation analysis
• Blocks Reports - 5-hour billing windows