> ## 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.

# Usage Analytics

> Build dashboards, billing reports, and cost breakdowns from aggregated usage data

## 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

```typescript theme={null}
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)

```typescript theme={null}
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:

```typescript theme={null}
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

```typescript theme={null}
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

<CardGroup cols={2}>
  <Card title="Request History" icon="clock-rotate-left" href="/cookbook/request-history">
    Show individual request logs with filtering and export
  </Card>

  <Card title="Meters & Pricing" icon="tags" href="/monetize/meters">
    Configure usage-based pricing rules
  </Card>
</CardGroup>