Docs/Reference/REST API

REST API Reference

Direct API integration with clean subdomain URLs and Bearer token authentication.

Quick Start

Get your API key from Settings.

Make your first request

curl -X POST https://api.costlens.dev/integrations/run \
  -H "Authorization: Bearer $COSTLENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","model":"gpt-5.4","input":"{\"messages\":[...]}","output":"Hello","tokensUsed":100,"latency":800,"success":true}'

Verify response and start routing configuration.

Subdomain API

All API endpoints are at api.costlens.dev with Bearer token authentication.

Get your API key from Settings → API Keys in your dashboard.

Quick Test:

curl -X POST https://api.costlens.dev/integrations/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "model": "gpt-5.4", "input": "Hello", "output": "Hi there!", "tokensUsed": 10, "latency": 500, "success": true}'

Base URL

https://api.costlens.dev

Authentication

All API requests require authentication via API key in the Authorization header:

Authorization: Bearer your_api_key_here

Endpoints

Cost Analysis Endpoint

The /cost-analysis endpoint is under development.

Use /integrations/run to track AI calls and get cost data.

POST /integrations/batch

Process multiple AI requests in a single call for 3-5x better performance.

Performance Benefits

3-5x faster than individual requests
Reduced HTTP overhead via batching
90% more reliable with fewer failure points
Automatic optimization with smart routing

Request

POST https://api.costlens.dev/integrations/batch
Content-Type: application/json
Authorization: Bearer your_api_key_here

{
  "runs": [
    {
      "provider": "openai",
      "model": "gpt-5.4",
      "input": "Hello, how are you?",
      "output": "I'm doing well, thank you!",
      "tokensUsed": 150,
      "latency": 1200,
      "success": true
    },
    {
      "provider": "anthropic",
      "model": "claude-3",
      "input": "What's the weather like?",
      "output": "I don't have access to real-time weather data.",
      "tokensUsed": 200,
      "latency": 1000,
      "success": true
    }
  ]
}

Response

{
  "success": true,
  "processed": 2,
  "errors": 0,
  "runs": [
    {
      "id": "run_123",
      "requestId": "req_123",
      "provider": "openai",
      "model": "gpt-5.4",
      "success": true
    }
  ],
  "batchStats": {
    "totalRuns": 2,
    "successful": 2,
    "failed": 0,
    "successRate": 100
  }
}

Batch Size Limits

Plan	Max Batch Size	Rate Limit
Free	10 requests	5 batches/minute
Pro	50 requests	20 batches/minute
Enterprise	200 requests	100 batches/minute

POST /integrations/run

Track an AI API call.

Request

POST https://api.costlens.dev/integrations/run
Content-Type: application/json
Authorization: Bearer your_api_key_here

{
  "provider": "openai",
  "model": "gpt-5.4",
  "input": "{\"messages\":[...]}",
  "output": "Hello! How can I help you?",
  "tokensUsed": 150,
  "latency": 1234,
  "success": true,
  "promptId": "greeting-v1"
}

Response

{
  "success": true,
  "run": {
    "id": "run_abc123",
    "requestId": "req_123",
    "correlationId": "corr_456",
    "provider": "openai",
    "model": "gpt-5.4",
    "success": true
  }
}

GET /analytics/overview

Get analytics overview.

Example Request

GET https://api.costlens.dev/analytics/overview?startDate=2025-01-01&endDate=2025-01-31

Query Parameters

startDate (ISO 8601) - Start date for analytics
endDate (ISO 8601) - End date for analytics

Response

{
  "totalRuns": 1234,
  "totalCost": 45.67,
  "totalTokens": 123456,
  "avgCostPerRun": 0.037,
  "successRate": 98.5,
  "avgLatency": 1234,
  "dailyData": [
    {
      "date": "2025-01-15",
      "runs": 25,
      "cost": 1.25,
      "tokens": 2500
    }
  ],
  "byModel": [
    {
      "model": "gpt-5.4",
      "runs": 800,
      "cost": 30.50
    }
  ],
  "byProvider": [
    {
      "provider": "openai",
      "runs": 1000,
      "cost": 35.20
    }
  ]
}

GET /usage

Get current usage stats.

Example Request

GET https://api.costlens.dev/usage

Response

{
  "plan": "free",
  "runsThisMonth": 234,
  "runsLimit": 1000,
  "percentUsed": 23.4
}

Supported Providers

CostLens currently supports OpenAI and Anthropic APIs with automatic cost optimization.

OpenAI

GPT-5.4, o1
GPT-5.4-mini-turbo
Automatic routing for cost savings

Anthropic

Claude Sonnet 4.6, Sonnet
Claude Haiku 4.5
Quality-aware routing

GET /dashboard/stats Advanced Analytics

Get comprehensive analytics including ML-powered cost forecasting and routing decisions.

Request

GET https://api.costlens.dev/dashboard/stats
Authorization: Bearer your_api_key_here

Response

{
  "success": true,
  "data": {
    "totalRuns": 1247,
    "totalCost": 45.67,
    "savings": { "total": 23.45, "roi": 51 },
    "costForecast": {
      "next7Days": 12.34,
      "next30Days": 52.10,
      "confidence": 78,
      "trend": "increasing",
      "factors": ["Usage trending upward", "Higher weekday usage"]
    },
    "routingDecisions": {
      "total": 1247,
      "enforced": 892,
      "qualityUpgrades": 45,
      "costDowngrades": 310
    },
    "providerStats": [
      {
        "provider": "openai",
        "requests": 847,
        "cost": 32.10,
        "avgLatency": 1200,
        "successRate": 0.98,
        "qualityScore": 0.92
      }
    ]
  }
}

POST /routing/context-aware Context-Aware Routing

Routes requests to the cheapest adequate model based on prompt complexity.

Example Request

POST https://api.costlens.dev/routing/context-aware
Content-Type: application/json
Authorization: Bearer your_api_key_here

{
  "prompt": "Summarize this research paper...",
  "preferences": {
    "priority": "quality",
    "maxLatencyMs": 3000,
    "qualityRequirement": "high"
  }
}

Response

{
  "success": true,
  "decision": {
    "provider": "openai",
    "model": "gpt-5.4-mini",
    "reason": "High quality requirement within latency target"
  }
}

GET /cost/predictive Predictive Analytics

30-day forecast, alerts, and optimization recommendations.

Example Request

GET https://api.costlens.dev/cost/predictive?windowDays=30&type=forecast
Authorization: Bearer your_api_key_here

Response

{
  "success": true,
  "forecast": {
    "projectedMonthlyCost": 123.45,
    "trend": "down",
    "confidence": 0.88
  },
  "alerts": [
    { "type": "spend", "level": "warning", "message": "Cost trending up for gpt-5.4" }
  ],
  "recommendations": [
    "Shift 20% traffic to claude-haiku-4.5 during off-peak",
    "Enable model enforcement on critical paths"
  ]
}

Rate Limits & Performance

Rate limits are per API key with performance optimizations:

Plan	Requests/Minute	Batch Size
Free	60	10 runs
Starter	300	25 runs
Pro	1,000	50 runs
Enterprise	5,000	50 runs

Performance Optimizations

Authentication Caching: 5-minute cache reduces auth overhead by 90%
Batch Processing: Process up to 50 runs in a single request for 3-5x better performance
Circuit Breaker: Automatic protection against external API failures
Connection Pooling: Optimized database connections for better performance

Rate Limit Response

When rate limited, you'll receive:

{
  "error": "Rate limit exceeded",
  "retryAfter": 60
}

Error Codes

Code	Meaning
401	Unauthorized - Invalid API key
402	Payment Required - Upgrade needed
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Example: cURL

# Track AI Call
curl -X POST https://api.costlens.dev/integrations/run \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "model": "gpt-5.4",
    "input": "{\"messages\":[...]}",
    "output": "Hello!",
    "tokensUsed": 150,
    "latency": 1234,
    "success": true
  }'

# Batch Processing (NEW - 3-5x faster)
curl -X POST https://api.costlens.dev/integrations/batch \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "runs": [
      {
        "provider": "openai",
        "model": "gpt-5.4",
        "input": "First prompt",
        "output": "First response",
        "tokensUsed": 150,
        "latency": 1200,
        "success": true,
        "requestId": "req_123"
      },
      {
        "provider": "anthropic",
        "model": "claude-3",
        "input": "Second prompt",
        "output": "Second response",
        "tokensUsed": 200,
        "latency": 1000,
        "success": true,
        "requestId": "req_124"
      }
    ]
  }'

# Get Analytics
curl -X GET "https://api.costlens.dev/analytics/overview?startDate=2025-01-01&endDate=2025-01-31" \
  -H "Authorization: Bearer your_api_key_here"

# Get Usage
curl -X GET https://api.costlens.dev/usage \
  -H "Authorization: Bearer your_api_key_here"

← SDK

Errors →

Docs/Reference/REST API

REST API Reference

Direct API integration with clean subdomain URLs and Bearer token authentication.

Quick Start

Get your API key from Settings.

Make your first request

curl -X POST https://api.costlens.dev/integrations/run \
  -H "Authorization: Bearer $COSTLENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","model":"gpt-5.4","input":"{\"messages\":[...]}","output":"Hello","tokensUsed":100,"latency":800,"success":true}'

Verify response and start routing configuration.

Subdomain API

All API endpoints are at api.costlens.dev with Bearer token authentication.

Get your API key from Settings → API Keys in your dashboard.

Quick Test:

curl -X POST https://api.costlens.dev/integrations/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "model": "gpt-5.4", "input": "Hello", "output": "Hi there!", "tokensUsed": 10, "latency": 500, "success": true}'

Base URL

https://api.costlens.dev

Authentication

All API requests require authentication via API key in the Authorization header:

Authorization: Bearer your_api_key_here

Endpoints

Cost Analysis Endpoint

The /cost-analysis endpoint is under development.

Use /integrations/run to track AI calls and get cost data.

POST /integrations/batch

Process multiple AI requests in a single call for 3-5x better performance.

Performance Benefits

3-5x faster than individual requests
Reduced HTTP overhead via batching
90% more reliable with fewer failure points
Automatic optimization with smart routing

Request

POST https://api.costlens.dev/integrations/batch
Content-Type: application/json
Authorization: Bearer your_api_key_here

{
  "runs": [
    {
      "provider": "openai",
      "model": "gpt-5.4",
      "input": "Hello, how are you?",
      "output": "I'm doing well, thank you!",
      "tokensUsed": 150,
      "latency": 1200,
      "success": true
    },
    {
      "provider": "anthropic",
      "model": "claude-3",
      "input": "What's the weather like?",
      "output": "I don't have access to real-time weather data.",
      "tokensUsed": 200,
      "latency": 1000,
      "success": true
    }
  ]
}

Response

{
  "success": true,
  "processed": 2,
  "errors": 0,
  "runs": [
    {
      "id": "run_123",
      "requestId": "req_123",
      "provider": "openai",
      "model": "gpt-5.4",
      "success": true
    }
  ],
  "batchStats": {
    "totalRuns": 2,
    "successful": 2,
    "failed": 0,
    "successRate": 100
  }
}

Batch Size Limits

Plan	Max Batch Size	Rate Limit
Free	10 requests	5 batches/minute
Pro	50 requests	20 batches/minute
Enterprise	200 requests	100 batches/minute

POST /integrations/run

Track an AI API call.

Request

POST https://api.costlens.dev/integrations/run
Content-Type: application/json
Authorization: Bearer your_api_key_here

{
  "provider": "openai",
  "model": "gpt-5.4",
  "input": "{\"messages\":[...]}",
  "output": "Hello! How can I help you?",
  "tokensUsed": 150,
  "latency": 1234,
  "success": true,
  "promptId": "greeting-v1"
}

Response

{
  "success": true,
  "run": {
    "id": "run_abc123",
    "requestId": "req_123",
    "correlationId": "corr_456",
    "provider": "openai",
    "model": "gpt-5.4",
    "success": true
  }
}

GET /analytics/overview

Get analytics overview.

Example Request

GET https://api.costlens.dev/analytics/overview?startDate=2025-01-01&endDate=2025-01-31

Query Parameters

startDate (ISO 8601) - Start date for analytics
endDate (ISO 8601) - End date for analytics

Response

{
  "totalRuns": 1234,
  "totalCost": 45.67,
  "totalTokens": 123456,
  "avgCostPerRun": 0.037,
  "successRate": 98.5,
  "avgLatency": 1234,
  "dailyData": [
    {
      "date": "2025-01-15",
      "runs": 25,
      "cost": 1.25,
      "tokens": 2500
    }
  ],
  "byModel": [
    {
      "model": "gpt-5.4",
      "runs": 800,
      "cost": 30.50
    }
  ],
  "byProvider": [
    {
      "provider": "openai",
      "runs": 1000,
      "cost": 35.20
    }
  ]
}

GET /usage

Get current usage stats.

Example Request

GET https://api.costlens.dev/usage

Response

{
  "plan": "free",
  "runsThisMonth": 234,
  "runsLimit": 1000,
  "percentUsed": 23.4
}

Supported Providers

CostLens currently supports OpenAI and Anthropic APIs with automatic cost optimization.

OpenAI

GPT-5.4, o1
GPT-5.4-mini-turbo
Automatic routing for cost savings

Anthropic

Claude Sonnet 4.6, Sonnet
Claude Haiku 4.5
Quality-aware routing

GET /dashboard/stats Advanced Analytics

Get comprehensive analytics including ML-powered cost forecasting and routing decisions.

Request

GET https://api.costlens.dev/dashboard/stats
Authorization: Bearer your_api_key_here

Response

{
  "success": true,
  "data": {
    "totalRuns": 1247,
    "totalCost": 45.67,
    "savings": { "total": 23.45, "roi": 51 },
    "costForecast": {
      "next7Days": 12.34,
      "next30Days": 52.10,
      "confidence": 78,
      "trend": "increasing",
      "factors": ["Usage trending upward", "Higher weekday usage"]
    },
    "routingDecisions": {
      "total": 1247,
      "enforced": 892,
      "qualityUpgrades": 45,
      "costDowngrades": 310
    },
    "providerStats": [
      {
        "provider": "openai",
        "requests": 847,
        "cost": 32.10,
        "avgLatency": 1200,
        "successRate": 0.98,
        "qualityScore": 0.92
      }
    ]
  }
}

POST /routing/context-aware Context-Aware Routing

Routes requests to the cheapest adequate model based on prompt complexity.

Example Request

POST https://api.costlens.dev/routing/context-aware
Content-Type: application/json
Authorization: Bearer your_api_key_here

{
  "prompt": "Summarize this research paper...",
  "preferences": {
    "priority": "quality",
    "maxLatencyMs": 3000,
    "qualityRequirement": "high"
  }
}

Response

{
  "success": true,
  "decision": {
    "provider": "openai",
    "model": "gpt-5.4-mini",
    "reason": "High quality requirement within latency target"
  }
}

GET /cost/predictive Predictive Analytics

30-day forecast, alerts, and optimization recommendations.

Example Request

GET https://api.costlens.dev/cost/predictive?windowDays=30&type=forecast
Authorization: Bearer your_api_key_here

Response

{
  "success": true,
  "forecast": {
    "projectedMonthlyCost": 123.45,
    "trend": "down",
    "confidence": 0.88
  },
  "alerts": [
    { "type": "spend", "level": "warning", "message": "Cost trending up for gpt-5.4" }
  ],
  "recommendations": [
    "Shift 20% traffic to claude-haiku-4.5 during off-peak",
    "Enable model enforcement on critical paths"
  ]
}

Rate Limits & Performance

Rate limits are per API key with performance optimizations:

Plan	Requests/Minute	Batch Size
Free	60	10 runs
Starter	300	25 runs
Pro	1,000	50 runs
Enterprise	5,000	50 runs

Performance Optimizations

Authentication Caching: 5-minute cache reduces auth overhead by 90%
Batch Processing: Process up to 50 runs in a single request for 3-5x better performance
Circuit Breaker: Automatic protection against external API failures
Connection Pooling: Optimized database connections for better performance

Rate Limit Response

When rate limited, you'll receive:

{
  "error": "Rate limit exceeded",
  "retryAfter": 60
}

Error Codes

Code	Meaning
401	Unauthorized - Invalid API key
402	Payment Required - Upgrade needed
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Example: cURL

# Track AI Call
curl -X POST https://api.costlens.dev/integrations/run \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "model": "gpt-5.4",
    "input": "{\"messages\":[...]}",
    "output": "Hello!",
    "tokensUsed": 150,
    "latency": 1234,
    "success": true
  }'

# Batch Processing (NEW - 3-5x faster)
curl -X POST https://api.costlens.dev/integrations/batch \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "runs": [
      {
        "provider": "openai",
        "model": "gpt-5.4",
        "input": "First prompt",
        "output": "First response",
        "tokensUsed": 150,
        "latency": 1200,
        "success": true,
        "requestId": "req_123"
      },
      {
        "provider": "anthropic",
        "model": "claude-3",
        "input": "Second prompt",
        "output": "Second response",
        "tokensUsed": 200,
        "latency": 1000,
        "success": true,
        "requestId": "req_124"
      }
    ]
  }'

# Get Analytics
curl -X GET "https://api.costlens.dev/analytics/overview?startDate=2025-01-01&endDate=2025-01-31" \
  -H "Authorization: Bearer your_api_key_here"

# Get Usage
curl -X GET https://api.costlens.dev/usage \
  -H "Authorization: Bearer your_api_key_here"

← SDK

Errors →