Skip to main content

​
Overview

The session command displays Claude Code usage statistics grouped by conversation sessions. Each session represents an individual conversation or coding session with Claude, identified by a unique session ID.

​
Usage

ccusage session

​
Flags

​
Command-Specific Flags

​
--id
string
Load usage data for a specific session ID. Shows detailed information for a single session instead of listing all sessions.Short flag: -iExample: ccusage session --id abc123-def456

​
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 session --jq '.sessions[] | select(.totalCost > 1.0)'
​
--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. Displays detailed token usage for each model used.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
​
--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 (better for screenshots).
​
--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:
  • Session: Last two parts of session ID (for brevity)
  • Input: Input tokens
  • Output: Output tokens
  • Cache Creation: Cache creation tokens
  • Cache Read: Cache read tokens
  • Total: Total tokens
  • Cost: Total cost in USD
  • Models: Models used in session
  • Last Activity: Timestamp of last activity in session
Includes a totals row at the bottom.
In narrow terminals or with --compact flag, some columns (cache metrics and total tokens) may be hidden. A message will indicate compact mode is active.

​
JSON Output

With --json flag, outputs structured JSON: 
{
  "sessions": [
    {
      "sessionId": "abc123-def456-ghi789",
      "inputTokens": 125000,
      "outputTokens": 15000,
      "cacheCreationTokens": 50000,
      "cacheReadTokens": 10000,
      "totalTokens": 200000,
      "totalCost": 0.85,
      "lastActivity": "2024-03-15T14:30:00.000Z",
      "modelsUsed": ["claude-sonnet-4-20250514"],
      "modelBreakdowns": [
        {
          "model": "claude-sonnet-4-20250514",
          "inputTokens": 125000,
          "outputTokens": 15000,
          "cacheCreationTokens": 50000,
          "cacheReadTokens": 10000,
          "totalCost": 0.85
        }
      ],
      "projectPath": "/home/user/projects/myproject"
    }
  ],
  "totals": {
    "inputTokens": 125000,
    "outputTokens": 15000,
    "cacheCreationTokens": 50000,
    "cacheReadTokens": 10000,
    "totalTokens": 200000,
    "totalCost": 0.85
  }
}

​
Examples

​
List all sessions

ccusage session

​
View specific session details

ccusage session --id abc123-def456-ghi789

​
Filter sessions from March 2024

ccusage session --since 20240301 --until 20240331

​
Export session data to JSON

ccusage session --json > session-usage.json

​
Show detailed model breakdown per session

ccusage session --breakdown

​
Find expensive sessions using jq

ccusage session --jq '.sessions[] | select(.totalCost > 1) | {sessionId, totalCost}'

​
Get total cost of all sessions

ccusage session --jq '.totals.totalCost'

​
Session ID Format

Session IDs are unique identifiers assigned by Claude Code to each conversation. They typically follow a UUID-like format with multiple hyphen-separated segments. The table view shows only the last two segments for readability, but the full ID is available in JSON output and when using --id.
  • daily - View usage grouped by day
  • monthly - View usage grouped by month
  • weekly - View usage grouped by week
  • blocks - View usage by 5-hour billing blocks

Build docs developers (and LLMs) love

Get started for freeTalk to us