Skip to main content

​
Overview

The blocks command displays Claude Code usage statistics grouped by 5-hour billing blocks. This matches Claude’s billing cycle where usage is grouped into continuous 5-hour periods. The command helps track active sessions, monitor burn rates, and project costs.

​
Usage

ccusage blocks

​
Flags

​
Command-Specific Flags

​
--active
boolean
default:"false"
Show only the active block with projections. Provides detailed view of current session including burn rate and projected usage.Short flag: -a
​
--recent
boolean
default:"false"
Show blocks from the last 3 days (including active block). Useful for tracking recent usage patterns.Short flag: -r
​
--token-limit
string
Token limit for quota warnings. Can be a number (e.g., 500000) or “max” to use the highest token count from previous sessions.Short flag: -tExamples:
  • --token-limit 500000 - Set explicit limit
  • --token-limit max - Use max from history
​
--session-length
number
default:"5"
Session block duration in hours. Default is 5 hours to match Claude’s billing cycle.Short flag: -n
Changing this value from the default 5 hours will not match Claude’s actual billing blocks.

​
Common Flags

​
--since
string
Filter from date in YYYYMMDD format (e.g., 20240301).Short flag: -s
​
--until
string
Filter until date in YYYYMMDD format (e.g., 20240331).Short flag: -u
​
--json
boolean
default:"false"
Output in JSON format instead of a formatted table.Short flag: -j
​
--jq
string
Process JSON output with jq command. Requires jq binary installed. Implies —json.Short flag: -qExample: ccusage blocks --jq '.blocks[] | select(.isActive)'
​
--mode
enum
default:"auto"
Cost calculation mode:
  • auto: Use costUSD if exists, otherwise calculate from tokens
  • calculate: Always calculate costs from token counts
  • display: Always use pre-calculated costUSD values
Short flag: -mChoices: auto, calculate, display
​
--breakdown
boolean
default:"false"
Show per-model cost breakdown.Short flag: -b
​
--offline
boolean
default:"false"
Use cached pricing data for Claude models instead of fetching from API.Short flag: -ONegatable: Use --no-offline to disable
​
--order
enum
default:"asc"
Sort order:
  • asc: Oldest first
  • desc: Newest first
Short flag: -oChoices: asc, desc
​
--debug
boolean
default:"false"
Show pricing mismatch information for debugging.Short flag: -d
​
--debug-samples
number
default:"5"
Number of sample discrepancies to show in debug output.
​
--timezone
string
Timezone for date grouping (e.g., UTC, America/New_York, Asia/Tokyo). Default: system timezone.Short flag: -z
​
--locale
string
default:"en-US"
Locale for date/time formatting (e.g., en-US, ja-JP, de-DE).Short flag: -l
​
--compact
boolean
default:"false"
Force compact mode for narrow displays. Automatically enabled for terminals narrower than threshold.
​
--config
string
Path to configuration file. Default: auto-discovery.
​
--color
boolean
Enable colored output (default: auto). FORCE_COLOR=1 has the same effect.
​
--no-color
boolean
Disable colored output (default: auto). NO_COLOR=1 has the same effect.

​
Output Formats

​
Table Output (Default)

Displays a formatted table with columns:
  • Block Start: Start time of the billing block
  • Duration/Status: Duration for completed blocks, “ACTIVE” for current block, “(inactive)” for gaps
  • Models: Models used in the block
  • Tokens: Total tokens consumed
  • %: Percentage of token limit (if --token-limit is set)
  • Cost: Total cost in USD
For active blocks, additional rows show:
  • REMAINING: Tokens remaining before hitting limit
  • PROJECTED: Projected total usage if current burn rate continues
Compact mode is automatically enabled for narrow terminals. Time and duration formats are shortened to fit smaller displays.

​
Active Block Detail View

With --active flag, shows detailed information: 
Block Started: 2024-03-15 10:00:00 (2h 30m ago)
Time Remaining: 2h 30m

Current Usage:
  Input Tokens:     125,000
  Output Tokens:    15,000
  Total Cost:       $0.85

Burn Rate:
  Tokens/minute:    933
  Cost/hour:        $0.34

Projected Usage (if current rate continues):
  Total Tokens:     280,000
  Total Cost:       $1.70

Token Limit Status:
  Limit:            500,000 tokens
  Current Usage:    140,000 (28.0%)
  Remaining:        360,000 tokens
  Projected Usage:  56.0% OK

​
JSON Output

With --json flag, outputs structured JSON: 
{
  "blocks": [
    {
      "id": "block-1",
      "startTime": "2024-03-15T10:00:00.000Z",
      "endTime": "2024-03-15T15:00:00.000Z",
      "actualEndTime": null,
      "isActive": true,
      "isGap": false,
      "entries": 42,
      "tokenCounts": {
        "inputTokens": 125000,
        "outputTokens": 15000,
        "cacheCreationTokens": 50000,
        "cacheReadTokens": 10000
      },
      "totalTokens": 200000,
      "costUSD": 0.85,
      "models": ["claude-sonnet-4-20250514"],
      "burnRate": {
        "tokensPerMinute": 933,
        "costPerHour": 0.34,
        "tokensPerMinuteForIndicator": 933
      },
      "projection": {
        "totalTokens": 280000,
        "totalCost": 1.70
      },
      "tokenLimitStatus": {
        "limit": 500000,
        "projectedUsage": 280000,
        "percentUsed": 56.0,
        "status": "ok"
      },
      "usageLimitResetTime": "2024-03-15T15:00:00.000Z"
    }
  ]
}

​
Burn Rate and Projections

For active blocks, the command calculates:
  1. Burn Rate: Current rate of token/cost consumption
    • Tokens per minute
    • Cost per hour
  2. Projection: Estimated total usage if rate continues
    • Projected total tokens
    • Projected total cost
  3. Token Limit Status: Warnings when approaching limits
    • OK: < 80% of limit
    • WARNING: 80-100% of limit (yellow)
    • EXCEEDS: > 100% of limit (red)

​
Examples

​
View current active block

ccusage blocks --active

​
Track recent usage (last 3 days)

ccusage blocks --recent

​
Set token limit for monitoring

ccusage blocks --token-limit 500000

​
Use historical max as limit

ccusage blocks --token-limit max

​
Export block data to JSON

ccusage blocks --json > blocks-usage.json

​
Find blocks exceeding $1

ccusage blocks --jq '.blocks[] | select(.costUSD > 1)'

​
View active block with token warnings

ccusage blocks --active --token-limit 300000

​
Check if projected usage will exceed limit

ccusage blocks --active --token-limit max --json | jq '.blocks[0].tokenLimitStatus.status'

​
Understanding Billing Blocks

Claude Code groups usage into 5-hour billing blocks:
  • Each block starts when you begin a new session
  • Usage within the same 5-hour window is grouped together
  • Gaps between sessions (inactive periods) are marked as “(inactive)”
  • Active blocks show real-time usage and projections
The default 5-hour session length matches Claude’s billing cycle. Changing this value with --session-length will not align with actual billing.
  • daily - View usage grouped by day
  • monthly - View usage grouped by month
  • weekly - View usage grouped by week
  • session - View usage by session
  • statusline - Live monitoring status line

Build docs developers (and LLMs) love

Get started for freeTalk to us