USAIGE: Track Token Usage and Costs for Laravel AI SDK Requests

What Is USAIGE?

As AI features become standard in Laravel applications, keeping tabs on token consumption and API spend quickly becomes a real operational concern. USAIGE is a Laravel package that attaches observability directly to the Laravel AI SDK. It records every AI request as a "run" — capturing token counts, USD costs, provider and model details, request timing, and error status — then surfaces everything through a built-in web dashboard at /usaige.

Two Helpers, Three Lines of Code

The entire integration revolves around two global helpers. ai_run() opens a tracking context tied to a feature identifier, and ai_usage() records what the SDK response consumed:

$run = ai_run('summarize-document');

$response = Ai::text('Summarize: ' . $document->content);

$usage = ai_usage($run, $response);

USAIGE automatically detects the response shape, handling responses from the Laravel AI SDK, the OpenAI PHP SDK, and plain arrays without extra configuration. If none of those shapes match, you can pass token counts directly:

$usage = ai_usage($run, promptTokens: 200, completionTokens: 80);

Provider, Model, and Cost Resolution

USAIGE reads config/ai.php to populate the provider and model on each run automatically. Both values can be overridden per call, or you can pass a Lab enum directly:

$run = ai_run('classify-ticket', model: 'gpt-4o-mini', provider: 'openai');

Costs are stored with sub-cent precision. The ai_usages table keeps both prompt and completion token counts alongside the USD total per run, so you can query spend by feature, user, model, or date range using the AiRun Eloquent model.

User Tracking and Metadata

By default, each run is associated with auth()->id(). You can override the resolver globally when the default does not fit your application's auth model:

use Laraveljutsu\Usaige\Facades\Usaige;

Usaige::resolveUsersUsing(fn () => auth()->user()?->team_id);

Runs also accept arbitrary JSON metadata, which is useful for attaching tenant identifiers, ticket references, or any other contextual data:

$run = ai_run('generate-report', metadata: [
    'tenant_id' => $tenant->id,
    'ticket'    => 'PROJ-1042',
]);

When an AI call fails before ai_usage() is reached, you can record the failure explicitly:

$run->fail('Rate limit exceeded');

Built-In Dashboard

The package registers a dashboard at /usaige listing all runs with their status, provider, model, token counts, costs, and duration. Access is controlled through middleware configuration in config/usaige.php, or with a simple callback:

Usaige::auth(fn ($request) => $request->user()?->isAdmin());

The dashboard path, middleware, and database table names are all configurable through the published config file.

Installation

USAIGE requires PHP 8.5+, Laravel 11+, and laravel/ai ^0.8.1:

composer require laraveljutsu/usaige
php artisan migrate

Key Takeaways

• Two global helpers (ai_run() and ai_usage()) are all you need to start tracking.
• Automatically detects response shapes from the Laravel AI SDK, OpenAI PHP SDK, and plain arrays.
• Stores costs with sub-cent precision, queryable by feature, user, model, or date.
• Supports per-run metadata and custom user resolvers for multi-tenant or team-based apps.
• Ships with a built-in /usaige dashboard protected by configurable middleware.
• Explicit failure recording keeps your observability data complete even when AI calls throw errors.

Find the source code and full documentation on GitHub.

Source: Laravel News — USAIGE: Track Token Usage and Costs for Laravel AI SDK Requests