USAIGE: Laravel AI SDK Token & Cost Tracking | Mohamed Said [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://www.msaied.com) [ Home ](https://www.msaied.com) [ Projects ](https://www.msaied.com/projects) [ Articles ](https://www.msaied.com/articles) [ Certificates ](https://www.msaied.com/certificates) [ Contact ](https://www.msaied.com#contact-section) [ ](https://github.com/EG-Mohamed) [ Home ](https://www.msaied.com) [ Projects ](https://www.msaied.com/projects) [ Articles ](https://www.msaied.com/articles) [ Certificates ](https://www.msaied.com/certificates) [ Contact ](https://www.msaied.com#contact-section) [ home ](https://www.msaied.com) [ articles ](https://www.msaied.com/articles) USAIGE: Track Token Usage and Costs for Laravel AI SDK Requests On this page 1. [ What Is USAIGE? ](#what-is-usaige) 2. [ Two Helpers, Three Lines of Code ](#two-helpers-three-lines-of-code) 3. [ Provider, Model, and Cost Resolution ](#provider-model-and-cost-resolution) 4. [ User Tracking and Metadata ](#user-tracking-and-metadata) 5. [ Built-In Dashboard ](#built-in-dashboard) 6. [ Installation ](#installation) 7. [ Key Takeaways ](#key-takeaways) ![USAIGE: Track Token Usage and Costs for Laravel AI SDK Requests](https://cdn.msaied.com/298/4bde9881e94264e1805ff443a90199d3.png) [ Composer Pacakge ](https://www.msaied.com/articles?category=composer-pacakge) [ AI ](https://www.msaied.com/articles?category=ai) #Laravel #AI #Laravel AI SDK #Observability #Token Tracking #Composer Package USAIGE: Track Token Usage and Costs for Laravel AI SDK Requests ================================================================= 26 Jun 2026 3 min read ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said Table of contents 1. [ 01 What Is USAIGE? ](#what-is-usaige) 2. [ 02 Two Helpers, Three Lines of Code ](#two-helpers-three-lines-of-code) 3. [ 03 Provider, Model, and Cost Resolution ](#provider-model-and-cost-resolution) 4. [ 04 User Tracking and Metadata ](#user-tracking-and-metadata) 5. [ 05 Built-In Dashboard ](#built-in-dashboard) 6. [ 06 Installation ](#installation) 7. [ 07 Key Takeaways ](#key-takeaways) 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](https://github.com/ludoguenet/usaige) is a Laravel package that attaches observability directly to the [Laravel AI SDK](https://github.com/laravel/ai). 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: ```php $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: ```php $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: ```php $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: ```php 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: ```php $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: ```php $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: ```php 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`: ```bash 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](https://github.com/ludoguenet/usaige). --- *Source: [Laravel News — USAIGE: Track Token Usage and Costs for Laravel AI SDK Requests](https://laravel-news.com/usaige-track-token-usage-and-costs-for-laravel-ai-sdk-requests)* Found this useful? [ ](https://twitter.com/intent/tweet?url=https%3A%2F%2Fwww.msaied.com%2Farticles%2Fusaige-track-token-usage-and-costs-for-laravel-ai-sdk-requests&text=USAIGE%3A+Track+Token+Usage+and+Costs+for+Laravel+AI+SDK+Requests) [ ](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fwww.msaied.com%2Farticles%2Fusaige-track-token-usage-and-costs-for-laravel-ai-sdk-requests) Frequently Asked Questions ---------------------------- 3 questions Q01 Does USAIGE work with AI providers other than OpenAI? USAIGE reads provider and model information from `config/ai.php` and supports overriding both per call. It automatically detects response shapes from the Laravel AI SDK and the OpenAI PHP SDK, and you can pass token counts manually for any other provider. Q02 How do I restrict access to the USAIGE dashboard? Access is controlled through middleware settings in `config/usaige.php`. You can also pass a callback via `Usaige::auth(fn ($request) => $request->user()?->isAdmin())` to apply custom authorization logic. Q03 What happens if my AI call fails before ai\_usage() is called? You can record the failure explicitly by calling `$run->fail('Your error message')`, ensuring the run is still logged with an error status rather than left incomplete in the database. Continue reading More Articles --------------- [ View all ](https://www.msaied.com/articles) [ ![Filament v5 Preview: Schema Unification, Performance Shifts, and How to Prepare](https://cdn.msaied.com/340/1a05ca68637b898b676efb66f22e627f.png) filament laravel php ### Filament v5 Preview: Schema Unification, Performance Shifts, and How to Prepare Filament v5 is reshaping how panels, forms, and tables are composed. This deep-dive covers the confirmed archi... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 1 Jul 2026 4 min read Read ](https://www.msaied.com/articles/filament-v5-preview-schema-unification-performance-shifts-and-how-to-prepare) [ ![Laravel 13: New Features, Helpers, and Practical Upgrade Notes](https://cdn.msaied.com/339/58c4fa6fe9b6d25a2dac17c621b6f4c6.png) laravel laravel-13 upgrade ### Laravel 13: New Features, Helpers, and Practical Upgrade Notes Laravel 13 ships with async-first defaults, a leaner bootstrapping layer, and several quality-of-life helpers.... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 1 Jul 2026 3 min read Read ](https://www.msaied.com/articles/laravel-13-new-features-helpers-and-practical-upgrade-notes) [ ![Laravel 12: Structured Route Files, Slim Skeletons, and the New Application Bootstrapping](https://cdn.msaied.com/337/05b39d16d0f88a5fb94d0cf74049b88b.png) laravel laravel-12 upgrade ### Laravel 12: Structured Route Files, Slim Skeletons, and the New Application Bootstrapping Laravel 12 ships with a leaner skeleton, first-class route file organisation, and a revised application bootst... ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MJ.jpg) Mohamed Said 1 Jul 2026 3 min read Read ](https://www.msaied.com/articles/laravel-12-structured-route-files-slim-skeletons-and-the-new-application-bootstrapping) [ ![Mohamed Said](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed Said Laravel Backend Engineer ](https://www.msaied.com)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. Explore - [Home](https://www.msaied.com) - [Projects](https://www.msaied.com/projects) - [Articles](https://www.msaied.com/articles) - [Certificates](https://www.msaied.com/certificates) - [Contact](https://www.msaied.com#contact-section) Connect - [ hello@msaied.com ](mailto:hello@msaied.com) - [ +20 109 461 9204 ](tel:+201094619204) © 2026 Mohamed Said. All rights reserved. [ ](https://github.com/EG-Mohamed) [ ](https://www.linkedin.com/in/msaiedm/) [ ](https://wa.me/201094619204) [ ](mailto:hello@msaied.com) [ ](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view)