AI usage & limitsPro

What your product's AI costs this month: the spend against its budget and where it's heading, every day by model, and each API key against its limit. Edit the budget and its line glides to show what it means; a key at its limit pauses, an alert rises as the spend passes its mark. Live, on motion.

Installation

When to use

The page where a team sees what its AI costs this month: the spend against a budget, where it's heading, by model and by API key.
AI products that bill by usage and need limits people can set: a monthly budget that alerts or pauses, and a limit per key.

When not to use

One run's cost: Agent run viewer shows the tokens and cost of each step.
A customer's plan, card and invoices: Billing settings.

Usage

AI usage & limits with your own data: every prop has the sample as its default, so pass only what you have.

example.tsx

1"use client"
2
3import { useRef, useState } from "react"
4import { AiUsage, type AiUsageData, type AiUsageHandle } from "@/components/dashral/blocks/ai-usage"
5
6export default function Usage() {
7  const usage = useRef<AiUsageHandle>(null)
8  // Your month's usage, kept in state: a new object replaces what's shown.
9  const [month] = useState<AiUsageData>({
10    period: { label: "November", start: "2026-11-01", length: 30 },
11    models: [
12      { id: "large", name: "Large model" },
13      { id: "small", name: "Small model" },
14    ],
15    // One entry a day from the period's start, by model id; the last is today.
16    days: [
17      { large: { cost: 42.1, tokens: 7_000_000, requests: 2200 }, small: { cost: 8.4, tokens: 14_000_000, requests: 9800 } },
18      { large: { cost: 51.6, tokens: 8_600_000, requests: 2700 }, small: { cost: 9.9, tokens: 16_500_000, requests: 11200 } },
19    ],
20    keys: [
21      { id: "key_1", name: "Support bot", owner: "Support", spent: 61.2, limit: 400 },
22      { id: "key_2", name: "Website chat", owner: "Marketing", spent: 50.8, limit: null },
23    ],
24  })
25  // A request made while the page is open: usage.current?.record({ model: "small", key: "key_1", cost: 0.02, tokens: 3400 })
26  return (
27    <AiUsage
28      ref={usage}
29      usage={month}
30      limits={{ budget: 2000, onReached: "pause", alerts: [50, 80, 100] }}
31      live
32      // While the promise is pending Save shows it; a thrown Error's message shows beside it.
33      onLimitsChange={async (limits) => console.log("limits", limits)}
34      onKeyLimitChange={async (key, limit) => console.log(key.id, "limit", limit)}
35      onAlert={(percent, spent) => console.log(`${percent}% of the budget used: ${spent}`)}
36    />
37  )
38}

API reference

AiUsage

What a product's AI costs this period: the spend against the budget and where it's heading, every day by model (cost, tokens or requests), each model's share, and each API key against its limit. Edit the budget, what happens when it's reached and the alerts, and the bar shows what they'd mean before you save. Requests made while the page is open come in through the handle's record.

Prop	Type	Default
`title`	`React.ReactNode`	`"AI usage"`
`usage`	`AiUsageData` The period's usage. A new object replaces what's shown (and what `record` added), so keep yours in state.	`sample`
`limits`	`UsageLimits` The limits at first: saving here changes them.	`sample`
`currency`	`string` ISO 4217 code for every amount.	`"USD"`
`onLimitsChange`	`(limits: UsageLimits) => Promise<void> \| void` Save the budget, what happens when it's reached and the alerts. Save shows it's working while the promise is pending; a thrown Error's message shows beside it.	—
`onKeyLimitChange`	`(key: UsageKey, limit: number \| null) => Promise<void> \| void` Set a key's limit (null for none). Same as onLimitsChange: working while pending, a thrown Error's message shows.	—
`onAlert`	`(percent: number, spent: number) => void` The spend passed one of the alerts' marks while the page is open, by `record`.	—
`live`	`boolean` Shows "Live" in the header, breathing: say so while `record` is fed.	`false`
`ref`	`React.Ref<AiUsageHandle>`	—
`className`	`string`	—

UsageBudgetMeter

The spend on a bar against the budget: what's spent, where the period ends at this pace (striped, warning where it passes the budget), the budget as a line across it and the alerts' marks under it. Everything glides to new values, the budget's line too, so a budget being edited shows what it would mean.

Prop	Type	Default
`spent`	`number` Required.	—
`forecast`	`number` Required. Where the period ends at this pace: drawn on from the spend, striped, and in warning past the budget.	—
`budget`	`number` Required.	—
`alerts`	`number[]` Percentages of the budget marked under the bar; the ones passed fill in.	`[]`
`format`	`Intl.NumberFormat` Required.	—

UsageBurnUp

The spend adding up over the period against the budget's line: drawn in when it first shows, then going on dashed at this pace to the period's end, with a mark where that crosses the budget. Lines glide when the spend or the budget changes.

Prop	Type	Default
`days`	`number[]` Required. What each day cost, from the period's start; the last is today.	—
`period`	`UsagePeriod` Required.	—
`budget`	`number` Required.	—
`height`	`number`	`112`
`className`	`string`	—

UsageChart

Every day of the period as a bar, its models stacked in it; the days still to come drawn dashed at the average so far. Hover, or focus it and use the arrow keys, to read a day: the others fade back. Bars grow up from the axis when it first shows and glide to their new heights when the metric or the data changes.

Prop	Type	Default
`models`	`UsageModel[]` Required.	—
`days`	`Record<string, UsageAmount>[]` Required. One entry a day from the period's start; the last one is today.	—
`period`	`UsagePeriod` Required.	—
`metric`	`UsageMetric` Required.	—
`focus`	`string \| null` A model to pick out: the others fade back.	`null`
`day`	`number \| null` The day being read (from 0), or null.	`null`
`onDayChange`	`(day: number \| null) => void`	—
`format`	`Intl.NumberFormat` Required.	—
`height`	`number`	`232`

type UsageMetric

= "cost" | "tokens" | "requests"

type UsageAmount

What a model used in a day: what it cost (in the block's currency), its tokens, its requests.

Prop	Type	Default
`cost`	`number`	—
`tokens`	`number`	—
`requests`	`number`	—

type UsageModel

color is any CSS color; left out, the chart's palette in order (--chart-1 to --chart-5). icon is the model's or its provider's logo (an SVG, an <img>), shown in its row in place of the color swatch; the share bar keeps the color.

Prop	Type	Default
`id`	`string`	—
`name`	`string`	—
`color`	`string`	—
`icon`	`React.ReactNode`	—

type UsageKey

An API key, or anything else you bill against: an agent, a team. A key at its limit is paused.

Prop	Type	Default
`id`	`string`	—
`name`	`string`	—
`owner`	`string`	—
`spent`	`number`	—
`limit`	`number \| null`	—

type UsagePeriod

The billing period: its name ("November"), its first day ("2026-11-01") and how many days it has.

Prop	Type	Default
`label`	`string`	—
`start`	`string`	—
`length`	`number`	—

type AiUsageData

Prop	Type	Default
`period`	`UsagePeriod`	—
`models`	`UsageModel[]`	—
`days`	`Record<string, UsageAmount>[]` One entry a day from the period's start, by model id; the last one is today.	—
`keys`	`UsageKey[]`	—

type UsageLimits

The month's budget, what happens when it's reached ("alert", or "pause" every request until the next period), and the percentages of it that raise an alert.

Prop	Type	Default
`budget`	`number`	—
`onReached`	`"alert" \| "pause"`	—
`alerts`	`number[]`	—

type UsageEvent

One request, or a batch of them, as it's made: today's numbers, its model's and its key's grow by it.

Prop	Type	Default
`model`	`string`	—
`key`	`string`	—
`cost`	`number`	—
`tokens`	`number`	—
`requests`	`number`	—

type AiUsageHandle

Prop	Type	Default
`record`	`(event: UsageEvent) => void` Adds a request to today: the numbers turn, today's bar grows, and the alerts and key limits it passes go off. Left out while it's paused (the budget reached with "pause", or its key at its limit): a paused request never ran.	—