Quick Start Guide

Integrate CostLens in under 2 minutes.

Instant Mode

Start optimizing costs immediately without CostLens API key. Perfect for development and testing.

1. Install

npm install costlens

2. Use

import { CostLens } from 'costlens';
import OpenAI from 'openai';

// No CostLens API key needed
const costlens = new CostLens();
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const ai = costlens.wrapOpenAI(openai);

const response = await ai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello' }]
});
// ✅ Automatically optimized and routed to cheaper model!

Cloud Mode

Full feature set with usage tracking, analytics, and team management.

1. Install

npm install costlens

2. Configure

# .env
COSTLENS_API_KEY=cl_your_api_key_here
OPENAI_API_KEY=sk-...

3. Use

import { CostLens } from 'costlens';
import OpenAI from 'openai';

const costlens = new CostLens({ 
  apiKey: process.env.COSTLENS_API_KEY 
});
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const ai = costlens.wrapOpenAI(openai);

const response = await ai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello' }]
});

Sign Up

1 minute

1. Go to costlens.dev
2. Click "Start Tracking Free"
3. Sign up with email or Google/GitHub
4. You're in! Free tier includes 1,000 runs/month

Get Your API Key

1 minute

1. Go to Settings
2. Click "Create Key"
3. Name it (e.g., "Production")
4. Copy the key now - you won't see it again!
5. Save it to your .env file

COSTLENS_API_KEY=cl_your_key_here

Install SDK

30 seconds

npm install costlens

Add 2 Lines of Code

2 minutes

For OpenAI (Recommended - Auto-saving):

import { CostLens } from 'costlens';
import OpenAI from 'openai';

const openai = new OpenAI();
const costlens = new CostLens({ 
  apiKey: process.env.COSTLENS_API_KEY,
  autoOptimize: false,   // 🚀 Cost tracking (feature in development)
  smartRouting: true,    // 🚀 Routes to cheapest model
  enableCache: true,     // 🚀 Savings on repeated queries
  costLimit: 0.10        // 🚀 Prevents budget overruns
});

// Wrap your client - savings happen automatically!
const tracked = costlens.wrapOpenAI(openai);

// Use it exactly like normal OpenAI with prompt tagging
const result = await tracked.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }]
}, {
  promptId: 'user-greeting',  // 📊 Track costs by use case
  userId: 'user-123'          // 📊 Track costs by user
});
// ✅ Prompt optimized, routed to cheaper model, cached, and tracked!

💰 Money-saving features: smartRouting uses GPT-3.5 for simple queries (20x cheaper), and caching saves on repeated prompts. Real-time cost tracking helps you optimize spending.

📊 Analytics included: Track costs by prompt type, user, model, and provider. See real savings, success rates, and performance metrics in your dashboard.

For Anthropic:

import { CostLens } from 'costlens';
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic();
const costlens = new CostLens({ 
  apiKey: process.env.COSTLENS_API_KEY 
});

// Wrap and use
const tracked = costlens.wrapAnthropic(anthropic);

const result = await tracked.messages.create({
  model: 'claude-3-opus-20240229',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello!' }]
});
// ✅ Done!

View Your Analytics Dashboard

30 seconds

1. Make a few API calls with prompt tagging
2. Go to Dashboard and Analytics
3. See detailed cost breakdowns and savings! 🎉

What You'll See in Analytics:

📊 Cost Tracking

Daily cost trends and usage patterns
Cost breakdown by model (GPT-4, GPT-3.5, Claude)
Cost breakdown by prompt ID and user
Provider comparison (OpenAI vs Anthropic)

💰 Savings Analytics

Real $ saved from smart routing
Cache hit rates and cache savings
Success rates and latency metrics
Export data to CSV for reporting

Advanced: Prompt Tagging for Cost Attribution

2 minutes

Tag your prompts to track costs by feature, user, or use case. Perfect for understanding which parts of your app cost the most.

// Tag by feature
await tracked.chat.completions.create({
  model: 'gpt-4',
  messages: [...]
}, {
  promptId: 'code-review',
  userId: 'user-123'
});

// Tag by use case  
await tracked.chat.completions.create({
  model: 'gpt-4',
  messages: [...]
}, {
  promptId: 'customer-support',
  correlationId: 'ticket-456'
});

// Tag by user type
await tracked.chat.completions.create({
  model: 'gpt-4', 
  messages: [...]
}, {
  promptId: 'premium-user-query',
  userId: 'premium-user-789'
});

💡 Pro tip: Use consistent promptId naming (e.g., 'feature-action') to group related costs in your analytics dashboard.

You're Saving Money! 💰

Your AI costs are being optimized automatically. Check your analytics dashboard to see:

Real $ savings from GPT-4 → GPT-3.5 smart routing
Cost breakdown by prompt ID, user, and model
Cache hit rates and performance metrics
Provider comparison (OpenAI vs Anthropic costs)
Daily trends and usage patterns
Export capabilities for reporting and analysis

Next Steps

Explore Analytics Dashboard

See detailed cost breakdowns, savings, and performance metrics

Set Budget Alerts

Get notified before you overspend

Advanced Prompt Tagging

Track costs by feature, user, or use case

Common Issues

API key not working

Check it starts with cl_
Make sure you copied the whole key
Verify it wasn't deleted in Settings

Not seeing data

Wait 1-2 minutes for sync
Check browser console for errors
Verify you're calling trackOpenAI() or trackAnthropic()

Need Help?

Full Guide: OpenAI Integration

API Docs: API Reference

Email: support@costlens.dev

Back to Documentation

Quick Start Guide

Integrate CostLens in under 2 minutes.

Instant Mode

Start optimizing costs immediately without CostLens API key. Perfect for development and testing.

1. Install

npm install costlens

2. Use

import { CostLens } from 'costlens';
import OpenAI from 'openai';

// No CostLens API key needed
const costlens = new CostLens();
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const ai = costlens.wrapOpenAI(openai);

const response = await ai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello' }]
});
// ✅ Automatically optimized and routed to cheaper model!

Cloud Mode

Full feature set with usage tracking, analytics, and team management.

1. Install

npm install costlens

2. Configure

# .env
COSTLENS_API_KEY=cl_your_api_key_here
OPENAI_API_KEY=sk-...

3. Use

import { CostLens } from 'costlens';
import OpenAI from 'openai';

const costlens = new CostLens({ 
  apiKey: process.env.COSTLENS_API_KEY 
});
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const ai = costlens.wrapOpenAI(openai);

const response = await ai.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello' }]
});

Sign Up

1 minute

1. Go to costlens.dev
2. Click "Start Tracking Free"
3. Sign up with email or Google/GitHub
4. You're in! Free tier includes 1,000 runs/month

Get Your API Key

1 minute

1. Go to Settings
2. Click "Create Key"
3. Name it (e.g., "Production")
4. Copy the key now - you won't see it again!
5. Save it to your .env file

COSTLENS_API_KEY=cl_your_key_here

Install SDK

30 seconds

npm install costlens

Add 2 Lines of Code

2 minutes

For OpenAI (Recommended - Auto-saving):

import { CostLens } from 'costlens';
import OpenAI from 'openai';

const openai = new OpenAI();
const costlens = new CostLens({ 
  apiKey: process.env.COSTLENS_API_KEY,
  autoOptimize: false,   // 🚀 Cost tracking (feature in development)
  smartRouting: true,    // 🚀 Routes to cheapest model
  enableCache: true,     // 🚀 Savings on repeated queries
  costLimit: 0.10        // 🚀 Prevents budget overruns
});

// Wrap your client - savings happen automatically!
const tracked = costlens.wrapOpenAI(openai);

// Use it exactly like normal OpenAI with prompt tagging
const result = await tracked.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }]
}, {
  promptId: 'user-greeting',  // 📊 Track costs by use case
  userId: 'user-123'          // 📊 Track costs by user
});
// ✅ Prompt optimized, routed to cheaper model, cached, and tracked!

💰 Money-saving features: smartRouting uses GPT-3.5 for simple queries (20x cheaper), and caching saves on repeated prompts. Real-time cost tracking helps you optimize spending.

📊 Analytics included: Track costs by prompt type, user, model, and provider. See real savings, success rates, and performance metrics in your dashboard.

For Anthropic:

import { CostLens } from 'costlens';
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic();
const costlens = new CostLens({ 
  apiKey: process.env.COSTLENS_API_KEY 
});

// Wrap and use
const tracked = costlens.wrapAnthropic(anthropic);

const result = await tracked.messages.create({
  model: 'claude-3-opus-20240229',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello!' }]
});
// ✅ Done!

View Your Analytics Dashboard

30 seconds

1. Make a few API calls with prompt tagging
2. Go to Dashboard and Analytics
3. See detailed cost breakdowns and savings! 🎉

What You'll See in Analytics:

📊 Cost Tracking

Daily cost trends and usage patterns
Cost breakdown by model (GPT-4, GPT-3.5, Claude)
Cost breakdown by prompt ID and user
Provider comparison (OpenAI vs Anthropic)

💰 Savings Analytics

Real $ saved from smart routing
Cache hit rates and cache savings
Success rates and latency metrics
Export data to CSV for reporting

Advanced: Prompt Tagging for Cost Attribution

2 minutes

Tag your prompts to track costs by feature, user, or use case. Perfect for understanding which parts of your app cost the most.

// Tag by feature
await tracked.chat.completions.create({
  model: 'gpt-4',
  messages: [...]
}, {
  promptId: 'code-review',
  userId: 'user-123'
});

// Tag by use case  
await tracked.chat.completions.create({
  model: 'gpt-4',
  messages: [...]
}, {
  promptId: 'customer-support',
  correlationId: 'ticket-456'
});

// Tag by user type
await tracked.chat.completions.create({
  model: 'gpt-4', 
  messages: [...]
}, {
  promptId: 'premium-user-query',
  userId: 'premium-user-789'
});

💡 Pro tip: Use consistent promptId naming (e.g., 'feature-action') to group related costs in your analytics dashboard.

You're Saving Money! 💰

Your AI costs are being optimized automatically. Check your analytics dashboard to see:

Real $ savings from GPT-4 → GPT-3.5 smart routing
Cost breakdown by prompt ID, user, and model
Cache hit rates and performance metrics
Provider comparison (OpenAI vs Anthropic costs)
Daily trends and usage patterns
Export capabilities for reporting and analysis

Common Issues

API key not working

Check it starts with cl_
Make sure you copied the whole key
Verify it wasn't deleted in Settings

Not seeing data

Wait 1-2 minutes for sync
Check browser console for errors
Verify you're calling trackOpenAI() or trackAnthropic()

Need Help?

Full Guide: OpenAI Integration

API Docs: API Reference

Email: support@costlens.dev