Skip to main content

ApiUsageAnalytics

API usage analytics β€” LiteLLM SpendLog sync + composite actual cost merge + operational dashboard summary (Layer 2 Composite, Business tier).

Status​

KeyValue
Layercomposite
TierBusiness
Statusreleased
Version1.0.0
PriceFree (subscription)
CategoryAI / LLM

Overview​

Overview​

ApiUsageAnalytics is multi-saas-kit's Layer 2 Composite Plugin (Business tier). It adds an actual cost sync layer on top of AiRelay or project-owned API usage logs, updating estimated costs to LiteLLM SpendLog actual costs.

Customer billing, rate cards, internal safety margin, and negative-margin reconciliation are owned by the ApiBilling plugin. This plugin owns aggregation and actual cost synchronization for stored usage/cost logs.

Core Components​

CostBreakdownMerger (Pure)​

Extracted from apis.how's LiteLLMActualCostSynchronizer::applySpendLog cost merging logic.

Composite cost formula:

actual_cost = estimated_stt_cost + estimated_tts_cost + actual_llm_cost

7 breakdown fields enriched β€” actual_llm_cost / request_id / provider / model / prompt_tokens / completion_tokens / cost_coverage.

Existing fields preserved.

LiteLLMSpendLogClient​

Calls /spend/logs/v2?request_id=.... Bearer + x-litellm-api-key headers, 4xx/5xx/network exception β†’ null, configurable.

UsageSummaryAggregator (Pure)​

Read-model aggregator for operational dashboards, quota alerts, and reports. It accepts array/object iterables and does not depend on a project-specific ApiUsageLog Eloquent model.

  • totals for estimated_cost, actual_cost, effective_cost
  • counts for actualized, estimated-only, and missing request IDs
  • provider/model/service/status grouped summaries
  • effective cost uses actual cost first, then estimated cost fallback

Configuration​

return [
    'enabled' => env('PLG_API_USAGE_ANALYTICS_ENABLED', true),
    'litellm_admin' => [
        'base_url' => env('LITELLM_ADMIN_API_BASE'),
        'api_key' => env('LITELLM_ADMIN_API_KEY'),     // admin/master key
        'spend_log_path' => '/spend/logs/v2',
        'timeout_seconds' => 30,
    ],
    'cost_merging' => [
        'currency' => 'USD',
        'composite_source' => 'speech_composite_mixed_litellm_spend_log',
        'coverage_label' => 'llm_actual_tts_stt_estimated',
    ],
];

Usage​

$merger = CostBreakdownMerger::fromConfig(config('api-usage-analytics'));
$client = LiteLLMSpendLogClient::fromConfig(config('api-usage-analytics'));

$requestId = $merger->extractRequestId($log->cost_breakdown);
$payload = $client->fetch($requestId);
$merged = $merger->merge($log->cost_breakdown, $payload);
$log->forceFill([...$merged])->save();

Origin​

Extracted from apis.how's LiteLLMActualCostSynchronizer (119 LOC). Eloquent + pagination remain in project; only pure merge + HTTP fetch in plugin.

Dependencies​

  • AiRelay β€” LLM call relay_meta combines with SpendLog
  • ApiBilling plugin β€” owns customer billing, rate cards, safety margin, and reconciliation

Roadmap (Phase 3+)​

  • Standard Sync Artisan Command
  • OpenAI-compatible/LiteLLM-compatible SpendLog adapters
  • Chorus costs are consumed only if AgentCliBridge/ChorusBridge emits usage events
  • Filament Dashboard Page rendering UsageSummaryAggregator output
  • Per-tenant/user quota alerts
  • AiTracking integration

License​

MIT

Dependencies​

Demos​

πŸ›’ View on Plugin Store: store.codebase.how/plugins/api-usage-analytics