Package Exports
- usagepilot
- usagepilot/package.json
- usagepilot/storage
Readme
UsagePilot
Open-core usage tracking for AI applications. Record, aggregate, and bill for token consumption across tenants with 95% storage reduction.
The Problem
Building AI-powered SaaS applications comes with unique challenges:
- Token costs add up fast - Each API call to OpenAI, Anthropic, or other providers costs money
- Usage varies wildly - Some users consume 100x more tokens than others
- Attribution is complex - You need to track usage per user, team, and organization
- Storage explodes - Storing every API call creates massive databases
- Billing is manual - Converting usage data into invoices takes custom code
Why UsagePilot?
UsagePilot is purpose-built for AI token tracking in multi-tenant SaaS applications:
💾 95% Storage Reduction
- Aggregates usage into 60-minute windows instead of storing every event
- Keeps query performance under 100ms even at scale
- Automatically finalizes historical data for immutable storage
👥 True Multi-tenancy
- Flexible dimension-based tracking (user, team, organization, workspace, etc.)
- No rigid tenant structure - adapt to your application's needs
- Efficient indexing for fast lookups across any dimension
💳 Billing-Ready
- Integrates with Stripe, Orb, Metronome, and other billing providers
- Accurate cost calculation with up-to-date pricing models
- Export usage data in billing-friendly formats
🚀 Production Performance
- Sub-100ms queries for hourly aggregations
- Handles 10,000+ events per second
- Exponential backoff and retry for reliability
Installation
npm install usagepilot
# or
pnpm add usagepilot
# or
yarn add usagepilotBasic Usage
Initialize UsagePilot
import { UsagePilot } from "usagepilot";
import { PostgresStorage } from "usagepilot/storage";
// Define your dimension structure
type Dimensions = {
user_id: string;
team_id: string;
organization_id: string;
};
// Create the storage adapter
const storage = new PostgresStorage({
connectionString: process.env.DATABASE_URL,
// Optional configuration
batchSize: 100,
flushInterval: 30000, // 30 seconds
maxRetries: 3,
retryDelay: 1000,
});
// Initialize UsagePilot
const usage = new UsagePilot<Dimensions>({
storage,
});Track AI Usage with Vercel AI SDK
import { streamText } from "ai";
import { createOpenAI } from "@ai-sdk/openai";
// Create a fetch wrapper that tracks usage
const trackedFetch = usage.createFetch((req) => ({
user_id: req.headers.get("x-user-id"),
team_id: req.headers.get("x-team-id"),
organization_id: req.headers.get("x-organization-id"),
}));
// Create OpenAI instance with tracked fetch
const openai = createOpenAI({
apiKey: process.env.OPENAI_API_KEY,
fetch: trackedFetch,
});
// Use it with Vercel AI SDK
async function generateResponse(prompt: string, userId: string) {
const result = await streamText({
model: openai("gpt-4"),
prompt,
headers: {
"x-user-id": userId,
"x-team-id": "team_456",
"x-organization-id": "org_123",
},
});
// Usage is automatically tracked and stored!
return result;
}Query Usage Data
// Get usage for a specific organization this month
const startOfMonth = new Date();
startOfMonth.setDate(1);
startOfMonth.setHours(0, 0, 0, 0);
const result = await usage.query({
dimensions: {
organization_id: "org_123",
},
timeRange: {
start: startOfMonth,
end: new Date(),
},
});
// Calculate total tokens used
const totalTokens = result.aggregates.reduce(
(sum, agg) => sum + agg.metrics.totalTokens,
0,
);
console.log(`Organization used ${totalTokens} tokens this month`);Export for Billing
// Get daily usage for billing
const dailyUsage = await usage.query({
dimensions: {
organization_id: "org_123",
},
timeRange: {
start: billingPeriodStart,
end: billingPeriodEnd,
},
granularity: "day", // Aggregate by day
});
// Calculate total tokens from daily aggregates
const totalTokens = dailyUsage.aggregates.reduce(
(sum, agg) => sum + agg.metrics.totalTokens,
0,
);
// Send to your billing provider
await stripe.usageRecords.create({
subscription_item: "si_123",
quantity: totalTokens,
timestamp: Math.floor(Date.now() / 1000),
});Advanced Features
- Multiple Storage Backends: PostgreSQL, ClickHouse, Redis (coming soon)
- Provider Support: OpenAI, Anthropic, Google, Mistral, and more
- Real-time Dashboards: Pre-aggregated materialized views
- Anomaly Detection: Identify unusual usage patterns
- Cost Optimization: Track and optimize model usage
- GDPR Compliant: Built-in data retention policies
Documentation
For comprehensive documentation, visit https://github.com/usagepilot/usagepilot
Contributing
We welcome contributions! Please see our Contributing Guide for details.
License
UsagePilot is licensed under the MIT License. See LICENSE for details.