> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ccs.kaitran.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics

> Track usage metrics, costs, and session statistics across all providers

# Analytics Dashboard

The Analytics dashboard provides comprehensive visibility into your AI usage patterns, costs, and performance metrics across all configured providers — including Claude, CLIProxy OAuth providers, and CLIProxy multi-provider sources.

## Overview

Access analytics through the dashboard:

```bash theme={null}
ccs config
# Navigate to Analytics tab
```

<Tabs>
  <Tab title="Dark Theme">
    <Frame>
      <img src="https://mintcdn.com/ccs-7e541244/ZIh-b3XKOoSIE-qm/assets/screenshots/analytics.webp?fit=max&auto=format&n=ZIh-b3XKOoSIE-qm&q=85&s=8a8bd1e05584c1cecabe9803f5f5b52f" alt="Analytics Dashboard - Dark" width="4336" height="2806" data-path="assets/screenshots/analytics.webp" />
    </Frame>
  </Tab>

  <Tab title="Light Theme">
    <Frame>
      <img src="https://mintcdn.com/ccs-7e541244/ZIh-b3XKOoSIE-qm/assets/screenshots/analytics-light.webp?fit=max&auto=format&n=ZIh-b3XKOoSIE-qm&q=85&s=8e48a2b3b448ef76c7fe33c3acdda3e6" alt="Analytics Dashboard - Light" width="4336" height="2806" data-path="assets/screenshots/analytics-light.webp" />
    </Frame>
  </Tab>
</Tabs>

## Data Sources

<Note>Available since v7.51.0 — unified multi-provider analytics</Note>

CCS aggregates usage data from three sources into a single unified view:

<CardGroup cols={3}>
  <Card title="Claude Config" icon="message">
    Local session data from `~/.claude/` — costs, tokens, session history for Claude account profiles
  </Card>

  <Card title="CCS Instances" icon="server">
    Usage from all configured CCS profiles (GLM, API profiles, account profiles)
  </Card>

  <Card title="CLIProxy Multi-Provider" icon="arrows-rotate">
    Aggregated usage from all CLIProxy OAuth providers (Gemini, Codex, AGY, GHCP, Kimi, etc.)
  </Card>
</CardGroup>

### CLIProxy Background Sync

CLIProxy usage data syncs automatically every **5 minutes** in the background:

* Snapshot stored at `~/.ccs/cache/cliproxy-usage/latest.json`
* Dashboard reads from snapshot for instant load (no blocking API calls)
* Manual refresh available via the refresh button or API endpoint

## Key Metrics

Five summary cards display high-level metrics:

<CardGroup cols={2}>
  <Card title="Total Tokens" icon="file-lines">
    Combined input/output tokens across all providers
  </Card>

  <Card title="Total Cost" icon="dollar-sign">
    Aggregate spending across Claude, Gemini, GPT, GLM, Qwen models
  </Card>

  <Card title="Cache Tokens" icon="database">
    Tokens served from cache, reducing API costs
  </Card>

  <Card title="Input/Output Cost" icon="arrow-right-arrow-left">
    Breakdown of costs by request direction
  </Card>
</CardGroup>

## Dashboard Widgets

### Usage Trends

Area chart showing token/cost trends over time with:

* Configurable date ranges: 24H, 7D, 30D, Month, All Time
* Custom date picker for specific periods
* Auto-refresh with "Updated X ago" indicator
* **Daily and hourly granularity** — drill down to per-hour breakdowns

### Cost by Model

Horizontal bar chart breaking down costs per model:

* Claude Opus/Sonnet 4.6 Thinking
* Gemini 3 Pro / Flash variants
* GPT 5.2, GLM 4, Qwen3 Coder
* Color-coded bars for quick comparison

### Model Usage

Donut chart showing distribution of requests across models:

* Percentage breakdown by model
* Visual representation of dominant providers
* **Monthly aggregates** for billing overview

### Session Stats

* **Total Sessions**: Count of coding sessions
* **Avg Cost/Session**: Average spending per session
* **Recent Activity**: List of recent sessions with timestamps

### CLIProxy Stats

Real-time proxy performance metrics:

* **Success Rate**: Percentage with total/failed counts
* **Total Tokens**: Aggregate tokens through proxy
* **Models Used**: Per-model breakdown with request counts
* **Anomaly Detection**: Highlights unusual usage spikes or error rates

### Hourly Breakdown

<Note>Available since v7.51.0</Note>

Granular per-hour usage view:

* Token and cost breakdown by hour of day
* Identify peak usage patterns
* Useful for rate limit planning

## Time Range Controls

| Range    | Description                    |
| -------- | ------------------------------ |
| 24H      | Last 24 hours                  |
| 7D       | Last 7 days (default)          |
| 30D      | Last 30 days                   |
| Month    | Current calendar month         |
| All Time | Complete history               |
| Custom   | Date picker for specific range |

## API Endpoints

<Note>Available since v7.51.0 — programmatic access to analytics data</Note>

The CCS dashboard server exposes analytics endpoints at `http://localhost:3000`:

| Endpoint              | Method | Description                  |
| --------------------- | ------ | ---------------------------- |
| `/api/usage/summary`  | GET    | High-level aggregate totals  |
| `/api/usage/daily`    | GET    | Day-by-day breakdown         |
| `/api/usage/hourly`   | GET    | Hour-by-hour breakdown       |
| `/api/usage/models`   | GET    | Per-model usage and costs    |
| `/api/usage/sessions` | GET    | Session list with stats      |
| `/api/usage/insights` | GET    | Anomaly detection results    |
| `/api/usage/refresh`  | POST   | Trigger manual CLIProxy sync |

**Example:**

```bash theme={null}
# Get summary (requires ccs config running)
curl http://localhost:3000/api/usage/summary

# Force refresh CLIProxy data
curl -X POST http://localhost:3000/api/usage/refresh

# Get hourly breakdown
curl http://localhost:3000/api/usage/hourly
```

## Storage

<Note>
  Analytics data is stored locally. No data is sent to external servers.
</Note>

| Path                                      | Description                                     |
| ----------------------------------------- | ----------------------------------------------- |
| `~/.ccs/usage/`                           | Local session usage data                        |
| `~/.ccs/cache/cliproxy-usage/latest.json` | CLIProxy usage snapshot (refreshed every 5 min) |