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 (prompted on first visit)

Prerequisites

• Docker and Docker Compose
• LibreChat already running with MongoDB
• Access to LibreChat's nginx config (for proxy setup)

Installation

1. Clone the repo

cd /opt
git clone https://x-token-auth:{ACCESS_TOKEN}@bitbucket.org/zlalani/librechat-analytics.git
cd librechat-analytics

Or with SSH:

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

2. Configure environment

cp .env.example .env
nano .env

Set the following values:

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 is required to access the dashboard.
• Do NOT use & or other special characters in the API key (breaks URL parsing).
• mongodb in the URI is the container name of LibreChat's MongoDB — change if yours is different.

3. Build and run

docker compose up -d --build

The container automatically joins LibreChat's Docker network (librechat_default) so it can reach MongoDB. If your LibreChat network has a different name, edit docker-compose.yml and change the name: under the librechat network.

4. Configure Nginx

Edit LibreChat's nginx config to proxy the dashboard. The nginx config location depends on your setup:

• Standard deploy: /home/<user>/LibreChat/client/nginx.conf
• Alternate location: /opt/LibreChat/client/nginx.conf

Add this location block before the location /api block:

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

Then reload nginx:

docker exec LibreChat-NGINX nginx -s reload

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 https://your-domain/librechat-analytics/ in your browser.

On first visit you'll be prompted to enter the API key. It gets saved in your browser's localStorage so you only need to enter it once.

Updating

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

No need to reconfigure nginx or re-enter the API key after updates.

Ports

Service	Port	Notes
Analytics Dashboard	3001	Bound to 127.0.0.1 only (not exposed externally)
LibreChat	3080	No conflict
Code Interpreter	8000/8005	No conflict

The dashboard is only accessible externally through the nginx proxy.

Authentication

The dashboard is protected by an API key set in .env. When accessing the dashboard:

1. Browser prompts for the API key on first visit
2. Key is stored in browser localStorage
3. All API requests include the key in the x-api-key header

To reset the key in your browser: open DevTools (F12) > Application > Local Storage > delete analyticsApiKey, then refresh.

Cost Calculation

Costs come directly from LibreChat's transactions collection. LibreChat stores tokenValue = rawAmount x 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

Troubleshooting

No data showing:

• Check the time period — try 30D if there's no recent usage
• Check container logs: docker logs librechat-analytics --tail 20
• Verify MongoDB connection: the health endpoint should return {"status":"ok"}

API key not prompting:

• Clear localStorage: DevTools > Application > Local Storage > delete analyticsApiKey
• Hard refresh: Ctrl+Shift+R

Container can't reach MongoDB:

• Verify network: docker network inspect librechat_default — both mongodb and librechat-analytics should be listed
• If LibreChat uses a different network name, update docker-compose.yml

Nginx 502 Bad Gateway:

• Check the analytics container is running: docker ps | grep analytics
• Check it's on the right network: docker network inspect librechat_default