Session Reports

Track usage grouped by conversation sessions and project directories

The session command groups your Claude Code usage by conversation sessions, showing token consumption and costs for each session.

Basic Usage

ccusage session

This displays a table showing usage for each session, including:

• Session ID (last two parts displayed)
• Input and output tokens
• Cache creation and read tokens
• Total tokens consumed
• Total cost in USD
• Last activity timestamp
• Models used

Command Options

View Specific Session

Load detailed usage data for a specific session ID:

ccusage session --id abc123-def456

This shows full details for the specified session, including all token breakdowns and model usage.

Filter by Date Range

View sessions within a specific date range:

ccusage session --since 20250301 --until 20250307

Dates must be in YYYYMMDD format. Only sessions with activity in the specified range are shown.

Model Breakdown

See per-model costs within each session:

ccusage session --breakdown

This adds detailed rows showing token usage and costs for each model used in the session.

JSON Output

Export data in JSON format:

ccusage session --json

Standard Output

{
  "sessions": [
    {
      "sessionId": "project/abc123-def456",
      "inputTokens": 45230,
      "outputTokens": 12450,
      "cacheCreationTokens": 8900,
      "cacheReadTokens": 125000,
      "totalTokens": 191580,
      "totalCost": 0.45,
      "lastActivity": "2025-03-15T14:30:00.000Z",
      "modelsUsed": ["claude-sonnet-4-20250514"],
      "modelBreakdowns": [...],
      "projectPath": "/path/to/project"
    }
  ],
  "totals": {
    "inputTokens": 45230,
    "outputTokens": 12450,
    "cacheCreationTokens": 8900,
    "cacheReadTokens": 125000,
    "totalTokens": 191580,
    "totalCost": 0.45
  }
}

jq Integration

Process JSON output with jq for advanced filtering:

ccusage session --jq '.sessions[] | select(.totalCost > 0.5)'

The --id flag is useful for debugging specific conversation sessions or tracking costs for particular tasks.

Common Flags

--id, -i · string

Load usage data for a specific session ID

--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/time formatting (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

Most Recent Sessions

ccusage session --order desc

Expensive Sessions

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

Session with Full Breakdown

ccusage session --id abc123-def456 --breakdown

Sessions This Week

ccusage session --since 20250310 --until 20250316

Understanding Sessions

Session ID Format

Sessions are identified by their Claude Code session ID, which appears in the format:

project/directory-name/abc123-def456

In table output, only the last two parts are shown for brevity (abc123-def456).

Project Path

Each session includes a projectPath field in JSON output, showing the full path to the project directory where the session took place.

Last Activity

The lastActivity timestamp shows when the session was last used, helping you identify recent vs. old sessions.

Session Grouping

Important Terminology: What we call “sessionId” in reports is actually derived from the project directory structure (project/directory). The true Claude Code session ID is found in the JSONL filename and entries.

File structure:

projects/{project}/{sessionId}.jsonl

Where:

• {project} is the project directory name (used for grouping in reports)
• {sessionId}.jsonl is the actual Claude Code session ID

Use Cases

Track Individual Tasks

Find the cost of a specific coding session:

ccusage session --id abc123-def456

Identify Expensive Sessions

Find sessions that exceeded your budget:

ccusage session --jq '.sessions | sort_by(.totalCost) | reverse | .[0:5]'

Project-Level Analysis

Filter sessions by project path:

ccusage session --jq '.sessions[] | select(.projectPath | contains("myproject"))'

Model Usage Patterns

See which models were used in each session:

ccusage session --breakdown

Compact Mode

Session reports support compact mode, though the Last Activity column requires more width:

ccusage session --compact

In narrow terminals, some information may be truncated for readability.