LibreChat Analytics Dashboard

Usage analytics dashboard for LibreChat. Queries the existing MongoDB to show model/agent usage, costs, and top users with time filtering.

Features

• Overview — Total cost, tokens, active users, conversations with time-series charts
• Users — Top users ranked by cost with token and conversation counts
• Models — Model breakdown with prompt/completion token and cost split
• Agents — Agent usage with underlying model resolution
• Time Filtering — 24H, 7D, 30D, or custom date range
• Auto-refresh — Updates every 60 seconds
• API Key Auth — Dashboard protected by API key

Prerequisites

• Docker and Docker Compose
• Access to LibreChat's MongoDB (same Docker network)

Quick Start

1. Clone the repo

git clone git@bitbucket.org:zlalani/librechat-analytics.git
cd librechat-analytics

2. Configure environment

cp .env.example .env

Edit .env:

MONGO_URI=mongodb://mongodb:27017/LibreChat
DASHBOARD_API_KEY=your-secure-key-here
PORT=3001

Important: Change DASHBOARD_API_KEY to a secure value. This key is required to access the dashboard.

3. Build and run

docker compose up -d --build

4. Connect to LibreChat's Docker network

The analytics container needs to reach LibreChat's MongoDB. Connect it to the same network:

docker network connect librechat_default librechat-analytics

Note: If your LibreChat network has a different name, check with docker network ls.

5. Verify

# Health check (no auth required)
curl http://localhost:3001/health

# Test API (requires API key)
curl -H "x-api-key: your-secure-key-here" http://localhost:3001/api/summary?period=30d

6. Access the dashboard

Open http://localhost:3001 in your browser. You'll be prompted to enter the API key on first visit.

Nginx Proxy (Optional)

To expose via LibreChat's existing nginx, add to the nginx config (before location /api):

location /analytics/ {
    proxy_pass http://librechat-analytics:3001/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Then restart nginx:

docker exec <nginx-container> nginx -s reload

Dashboard will be available at https://your-domain/analytics/.

Server Deployment

On the server:

cd /opt
git clone git@bitbucket.org:zlalani/librechat-analytics.git
cd librechat-analytics
cp .env.example .env
# Edit .env with your MONGO_URI and DASHBOARD_API_KEY
docker compose up -d --build
docker network connect librechat_default librechat-analytics

Updating:

cd /opt/librechat-analytics
git pull
docker compose up -d --build

Ports

Service	Port	Notes
Analytics Dashboard	3001	Bound to 127.0.0.1 only

Does not clash with LibreChat (3080) or Code Interpreter (8000/8005).

Cost Calculation

Costs come directly from LibreChat's transactions collection. LibreChat stores tokenValue = rawAmount × rate where rate is USD per 1M tokens. The dashboard reads these pre-calculated values — it does not independently calculate pricing.

API Endpoints

All require x-api-key header. All accept ?period=24h|7d|30d|custom&start=ISO&end=ISO.

Endpoint	Description
GET /health	Health check (no auth)
GET /api/summary	Total tokens, cost, users, conversations
GET /api/top-users?limit=10	Users ranked by cost
GET /api/top-models?limit=10	Models ranked by cost (resolves agent IDs to underlying LLM)
GET /api/top-agents?limit=10	Agents ranked by cost
GET /api/cost-breakdown	Per-model input vs output cost split
GET /api/usage-over-time	Time-series tokens and cost