USAIGE: Laravel AI SDK Token & Cost Tracking | Mohamed Said [Skip to content](#main) [ ![](https://cdn.msaied.com/01KT78WE565VEMM3PSNQAAB0MH.png) Mohamed SaidLaravel Backend Engineer ](https://www.msaied.com/public) - [Home](https://www.msaied.com/public) - [Projects](https://www.msaied.com/public/projects) - [Articles](https://www.msaied.com/public/articles) - [Certificates](https://www.msaied.com/public/certificates) - [About](https://www.msaied.com/public#about) [ Contact](https://www.msaied.com/public#contact) Menu Menu ---- Close - [HomeStart here](https://www.msaied.com/public) - [ProjectsCase studies](https://www.msaied.com/public/projects) - [ArticlesEngineering notes](https://www.msaied.com/public/articles) - [CertificatesCredentials](https://www.msaied.com/public/certificates) - [AboutHow I work](https://www.msaied.com/public#about) - [ContactGet in touch](https://www.msaied.com/public#contact) [Start a conversation](https://www.msaied.com/public#contact) [WhatsApp](https://wa.me/201094619204) [Email](mailto:hello@msaied.com) 1. [Home](https://www.msaied.com/public) 2. / 3. [Articles](https://www.msaied.com/public/articles) 4. / 5. [Composer Pacakge](https://www.msaied.com/public/articles?category=composer-pacakge) 6. / 7. USAIGE: Track Token Usage and Costs for Laravel AI SDK Requests [Composer Pacakge](https://www.msaied.com/public/articles?category=composer-pacakge) [AI](https://www.msaied.com/public/articles?category=ai) USAIGE: Track Token Usage and Costs for Laravel AI SDK Requests ================================================================ USAIGE is a Laravel package that adds observability to the Laravel AI SDK, recording every AI request with token counts, costs, provider details, timing, and error status — all surfaced through a built-in dashboard. ![](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp) [Mohamed Said](https://www.msaied.com/public#person) Published 26 Jun 2026 · Updated 26 Jun 2026 · 3 min read ShareCopy linkCopied ![USAIGE: Track Token Usage and Costs for Laravel AI SDK Requests](https://cdn.msaied.com/298/4bde9881e94264e1805ff443a90199d3.png) 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) 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)* - [Laravel](https://www.msaied.com/public/articles?search=Laravel) - [AI](https://www.msaied.com/public/articles?search=AI) - [Laravel AI SDK](https://www.msaied.com/public/articles?search=Laravel%20AI%20SDK) - [Observability](https://www.msaied.com/public/articles?search=Observability) - [Token Tracking](https://www.msaied.com/public/articles?search=Token%20Tracking) - [Composer Package](https://www.msaied.com/public/articles?search=Composer%20Package) Frequently asked questions --------------------------- 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. 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. 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. ![Mohamed Said](https://cdn.msaied.com/01M22N44A70A5MC2S599JP0MPH.webp)About the author ---------------- [Mohamed Said](https://www.msaied.com/public#person)Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. [About](https://www.msaied.com/public#about) [GitHub ↗](https://github.com/EG-Mohamed) [LinkedIn ↗](https://www.linkedin.com/in/msaiedm/) [WhatsApp ↗](https://wa.me/201094619204) [Email Address ↗](mailto:hello@msaied.com) [My CV ↗](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view) [Previous articleLaravel WhatsApp: Send Messages via Meta Cloud API and whatsapp-web.js Behind One Facade](https://www.msaied.com/public/articles/laravel-whatsapp-send-messages-via-meta-cloud-api-and-whatsapp-webjs-behind-one-facade) [Next articleTurn PHP Attributes Into Docs With Signal](https://www.msaied.com/public/articles/turn-php-attributes-into-docs-with-signal) 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) ### Have a technical challenge? Tell me what you’re building. I reply within two working days. [Start a conversation](https://www.msaied.com/public#contact) Related articles ----------------- [ ![](https://cdn.msaied.com/740/cce86edc21eddcbdd2f2454fadaf9c70.png) · 3 min read### The Pipeline Pattern in Laravel: Custom Pipelines Beyond Middleware 5 Oct 2026 ](https://www.msaied.com/public/articles/the-pipeline-pattern-in-laravel-custom-pipelines-beyond-middleware-1) [ ![](https://cdn.msaied.com/739/2d6897fdcdcf090613f96f72a64b8a78.png) · 4 min read### MySQL Full-Text Search in Laravel: Indexes, Relevance Scoring, and Boolean Mode 4 Oct 2026 ](https://www.msaied.com/public/articles/mysql-full-text-search-in-laravel-indexes-relevance-scoring-and-boolean-mode) [ ![](https://cdn.msaied.com/738/073696a3fefe18bec825beec5ac658f5.png) · 4 min read### Laravel Queue Rate-Limited Middleware: Throttling Jobs Without Losing Work 4 Oct 2026 ](https://www.msaied.com/public/articles/laravel-queue-rate-limited-middleware-throttling-jobs-without-losing-work) Have a technical challenge? ---------------------------- Tell me what you’re building. I reply within two working days. [Discuss your project ↗](https://www.msaied.com/public#contact) © 2026 Mohamed Said · Built with Laravel, meant to last.Senior Backend Engineer specializing in Laravel, scalable SaaS platforms, APIs, and cloud infrastructure. I build secure, high-performance web applications that help businesses grow. - [Home](https://www.msaied.com/public) - [Articles](https://www.msaied.com/public/articles) - [Certificates](https://www.msaied.com/public/certificates) - [GitHub](https://github.com/EG-Mohamed) - [LinkedIn](https://www.linkedin.com/in/msaiedm/) - [WhatsApp](https://wa.me/201094619204) - [Email Address](mailto:hello@msaied.com) - [My CV](https://drive.google.com/file/u/0/d/1MF20IPRJyzfy32mhEutjL5EpSls0w2Q8/view) - [Sitemap](https://www.msaied.com/public/sitemap.xml)