Documentation Index
Fetch the complete documentation index at: https://lava.so/docs/llms.txt
Use this file to discover all available pages before exploring further.
Problem
You want to show usage dashboards, generate billing summaries, compare feature costs, or forecast monthly spend using aggregated data.
Solution
Use usage.retrieve() for daily rollups. It returns per-day breakdowns and period totals for tokens, requests, and costs.
Customer Dashboard
import { Lava } from '@lavapayments/nodejs';
const lava = new Lava();
async function getCustomerDashboard(customerId: string) {
const thirtyDaysAgo = new Date();
thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);
const usage = await lava.usage.retrieve({
start: thirtyDaysAgo.toISOString(),
customer_id: customerId,
});
return {
totalRequests: usage.totals.total_requests,
totalTokens: usage.totals.total_usage_tokens,
totalSpent: parseFloat(usage.totals.total_cost).toFixed(2),
dailyData: usage.items.map((day) => ({
date: day.date,
requests: day.total_requests,
tokens: day.total_usage_tokens,
cost: parseFloat(day.total_cost),
})),
};
}
Revenue Report (Merchant)
async function getRevenueReport(days: number = 30) {
const startDate = new Date();
startDate.setDate(startDate.getDate() - days);
const usage = await lava.usage.retrieve({
start: startDate.toISOString(),
});
return {
providerCosts: parseFloat(usage.totals.total_cost).toFixed(2),
totalRequests: usage.totals.total_requests,
totalCharge: parseFloat(usage.totals.total_charge).toFixed(2),
};
}
Compare Feature Costs
Tag requests with X-Lava-Metadata-Feature headers, then compare usage across features:
async function compareFeatures(features: string[]) {
const startDate = new Date();
startDate.setDate(startDate.getDate() - 30);
const results = await Promise.all(
features.map(async (feature) => {
const usage = await lava.usage.retrieve({
start: startDate.toISOString(),
metadata_filters: { feature },
});
return {
feature,
requests: usage.totals.total_requests,
tokens: usage.totals.total_usage_tokens,
cost: parseFloat(usage.totals.total_cost).toFixed(2),
};
})
);
return results.sort((a, b) => b.requests - a.requests);
}
// Example
const comparison = await compareFeatures(['chat', 'search', 'code-gen']);
Cost Forecasting
async function forecastMonthlyCost(customerId: string) {
const startOfMonth = new Date();
startOfMonth.setDate(1);
startOfMonth.setHours(0, 0, 0, 0);
const usage = await lava.usage.retrieve({
start: startOfMonth.toISOString(),
customer_id: customerId,
});
const daysElapsed = new Date().getDate();
const daysInMonth = new Date(
new Date().getFullYear(),
new Date().getMonth() + 1,
0
).getDate();
const currentSpend = parseFloat(usage.totals.total_cost);
return {
currentSpend: currentSpend.toFixed(2),
forecastedMonthly: ((currentSpend / daysElapsed) * daysInMonth).toFixed(2),
daysRemaining: daysInMonth - daysElapsed,
};
}
Next Steps
Request History
Show individual request logs with filtering and export
Meters & Pricing
Configure usage-based pricing rules