Track, attribute, and cap LLM costs per user, action, and custom tag in Convex with atomic admission control and a built-in admin dashboard.
npm install @convex-dev/ai-budgetThe @convex-dev/ai-budget component provides ai.users.setLimits() to configure daily spend, token, and requests-per-minute caps per user. Calls to ai.chat() or ai.languageModel() are automatically checked against these limits before the LLM request is made, throwing a ConvexError with kind 'AIBudgetLimit' when a hard cap is exceeded. Blocked attempts are still recorded so you can audit who is hitting limits.
ai.chat() returns costNanos, promptTokens, completionTokens, and cachedTokens for every call, and @convex-dev/ai-budget writes a full request log with messages, response, latency, and per-request cost to durable storage. Spend is rolled up into daily and monthly history per user, action, and any custom tag dimensions you define, and these rollups survive request log retention expiry.
Pass ai.languageModel(ctx, { userId }) as the languageModel option when constructing an Agent from @convex-dev/agent. This wraps every generation in the budget component's reserve-then-settle cycle, so each agent generation is attributed to the user, checked against their caps, priced using the gateway's authoritative cost, and written to the audit log without any additional instrumentation.
For long-running jobs that span multiple Convex functions, @convex-dev/ai-budget provides ai.begin() to reserve budget at job submission and ai.settle() to record actual cost when the job completes. Set reserveTtlMs to the job's maximum expected duration so the hold is not reaped mid-flight, and use ai.registerWebhook() to settle from a provider webhook.
@convex-dev/ai-budget runs in Convex's default V8 runtime and does not require 'use node'. The component is pure V8 and ai.chat() and ai.languageModel() use fetch-based requests, so they work in standard Convex actions without switching to the Node.js runtime.
@convex-dev/ai-budget uses a reserve-then-settle design where each request atomically reserves an estimated cost against every capped bucket it touches before the LLM call is made. This means two concurrent requests cannot both read the same remaining budget and both proceed past a cap. Final cost may differ from the estimate and is recorded at settlement, but the admission check is always atomic against live reserved amounts.
A nanodollar is one billionth of a US dollar, so $1.00 equals 1,000,000,000 nanodollars. @convex-dev/ai-budget uses integer nanodollars for all costs, limits, and prices to avoid the floating-point rounding drift that accumulates with fractional cent arithmetic, and to keep cap comparisons exact. The integer representation supports values up to approximately $9 million per field.
Yes. ai.meter() allows you to bring any external LLM or API call under the same caps, audit log, and cost tracking that ai.chat() uses. You provide a run callback that executes your provider call and returns token counts or an explicit costNanos value, and @convex-dev/ai-budget handles the reserve-then-settle cycle, cap enforcement, and request logging around it.
@convex-dev/ai-budget requires convex@^1.45 and a Convex team on a paid plan because it routes LLM calls through the Convex AI Gateway, which is a paid feature. The component itself installs via npm as @convex-dev/ai-budget and also requires @convex-dev/ai-sdk-provider and the ai package.