---
icon: 📊
---

# AI Usage Page

The AI Center page (`/platform/ai/usage`) that answers one question: **where is my AI money going?** These choices came from a grill session on 2026-10-20 and shape every screen. Cloud and self-hosted Enterprise only — the read API does not exist on Community — and it is listed under **AI Center → Usage** in the sidebar and in global search (launched 2026-11-15). The `production` scope is labelled **Published** in the UI, because "Production" confused admins; the default period is the last 7 days.

## Rules
- **Served by Autumn-copied data, not a live query.** The three endpoints read from our own Postgres copy of Autumn's usage, not Autumn itself — see [decision 000053](../decisions/000053-ai-usage-is-copied-from-autumn-into-our-postgres.md) for the why and its gotchas (ids Autumn drops as null, the copy's paging deadline). A platform with no billing connection has `trackingSince: null` forever.
- **One dollar unit.** Credits are converted at their dollar value; credits only appear as a note ("Includes 6,479 credits"). Never two units side by side.
- **Three scopes, one page.** A scope select whose options each carry an icon and a one-line description, in this order: **All** · **Production** (the default) · **Testing** (flow builder Test step and agent builder). No amounts on it. The whole page follows it. No separate testing section, never a toggle switch.
- **Controls sit in the header, right of the title**, on every usage page: scope select and period select (labels only, no date ranges), both styled like outline buttons. No export on the page.
- **Every row has two lines, so all cards share one row height.** Line two is the parent (a flow's project, a model's or key's provider), a project's flow and agent counts, or "Billed on your plan" for credits. Every key row keeps the same right-hand button slot, so the bars line up: external dashboard, or billing for credits.
- **No project spend limits.** Dropped on 2026-10-21 to keep the feature simple to build and maintain: no cap, no limits card, no Set limit dialog.
- **Credits are always "Activepieces credits" with the Activepieces logo**, wherever the analytics mention them.
- **See all is a list card, not a data table.** Search sits inside the card. Column headers are quiet text that sorts on click, with an arrow only on the active column. Numbers are right-aligned, and the name column takes the free width. The share bar sits under the name. Change, calls and tokens hide on small screens. Pagination is page by page: "1–25 of 134" on the left, previous / "Page 1 of 6" / next on the right, back to page 1 on search or sort. A "Show more" button was tried and dropped.
- **Exact vs estimated stays out of the headline.** It shows only on a key's detail page (reported by provider vs estimated from list prices, plus the provider dashboard link), and as one footnote on the overview.
- **Overview, then drill down.** Every item opens its own detail page (`/platform/ai/usage/:dimension/:id`), and every card has See all (`/platform/ai/usage/:dimension`). Period and scope ride in the URL.
- **Served by three endpoints, one cached SQL each:** `/v1/ai-usage/overview`, `/items?dimension`, `/items/:dimension/:id`. Spend is the `spendUsd` column frozen at write (managed = what we bill, own key = reported cost or list-price estimate). Storage is our own `ai_usage_5m` (3 days) + `ai_usage_daily` (13 months); Autumn is the billing truth only, not the analytics store.
- **Costs are marked as estimates where the money is, not in the subtitle.** A quiet "Estimated" link sits next to the hero's Spend label (hidden for calls and tokens, which are exact) and opens a "Why these numbers are estimates" popover: providers mostly return tokens, not cost; discounts, caching, batch rates and price changes shift the real bill; reported costs are used as is; Activepieces credits are exact; the provider dashboard is the billing truth. Putting the caveat first in the page header made the whole page read as untrustworthy (dropped 2026-10-21).
- **Empty overview is the real page at zero, not a splash.** Tiles read $0.00 and 0, the chart is a flat line, the donut is an empty grey ring, and cards show their small empty state. One slim note bar on top says why: never used → "No AI spend yet. It shows up a few minutes after the first AI step, agent run or chat message."; empty only for these filters → names the scope and period and offers "Show last 90 days" and "Include testing" / "Include production". A third state exists for self-hosted Enterprise with no billing connection (`trackingSince === null`): "AI usage isn't available on this install", with a one-line why — usage data comes from the billing connection, which the install does not have. List and detail pages use a compact left-aligned card with the same copy and buttons. Never link to provider setup from here. A centred splash and a ghost-preview panel were tried and dropped. The read API's has-any-usage flag (`history.hasAnyUsage`) tells never-used apart from filtered-empty (`usage-empty.tsx`).
- **Loading looks like the page.** Every surface is the real white card with grey bars inside it in the shape of its content: tiles, the hero with one block for the chart, the donut, and the list rows with their share bars. Every usage page has its own: overview, see-all list (search, header, rows), and detail (tiles, hero, donut for projects and agents, one card per related list). Never draw bare grey blocks in place of cards (`usage-skeletons.tsx`).
- **The title is the breadcrumb.** List: "AI usage / Users". Detail: "AI usage / Users / Maya Chen", whatever page you came from, so one click reaches the list. There is no back link above the title and no type badge; the period and scope carry over in every crumb. The trail is `AiCenterTrail` (`setup/ai/components/ai-center-trail.tsx`), shared across the AI Center: the provider key page uses it too ("Providers / key name"), so new AI Center sub-pages use it instead of a back link.
- **One detail template.** Header + the same chart + top 5 of the *other* dimensions + one extra card per type: project → spend with its flow and agent counts, flow → runs and cost per run, key → reported vs estimated, model → list price. A flow detail stops at flow level; there is no per-step split. A detail page with zero calls and zero previous spend shows the empty card but keeps the item's name in the breadcrumb.

- **"Previous period" means the same span right before**, except month views: "This month" and "Last month" compare with the same days of the month before (Oct 1–20 vs Sep 1–20). The chart legend reads its ranges straight from the read API's `ranges` field (not re-derived from chart point labels), since that is the only place the month-truncation rule is computed correctly.

- **Never compare against a period that isn't fully tracked.** If tracking started after the previous period began, every change % (hero, cards, lists) is hidden and the hero shows an info icon instead; a partial comparison would show fake growth like +400%. The "vs previous period" label lives in the change chip's tooltip, and there is no "tracking started" note (dropped 2026-11-15 as noise).

- **Every bar says what it is a share of.** Overview bars are a share of all AI spend in the period; detail-page bars are a share of that item's spend. Each bar shows its % and a tooltip that names the whole.

## Data hierarchy
- **Root: the platform**, which is the bill. Scope (Production / Testing / All) and period filter the whole page; they are not levels.
- **Tree 1, where the money is spent:** platform → project → flows · agents · chat by user. Project is the parent because project admins and ownership live there.
- **Tree 2, what it is spent on:** platform → provider → key → model. Keys are platform-owned and shared across projects, so they never sit under a project.
- **Side views, not levels:** user (who; only chat and agent runs have one) and source (what kind of work, an overlay on tree 1).
- **Detail pages pivot to the other tree:** a flow shows its models and keys, and a key shows its projects and flows.
- **A Run Agent step counts under both its flow and its agent**, marked Shared, so flows + agents can add up to more than the project total. Decided 2026-10-20. A two-tree overview layout was tried as "Usage v2" and dropped the same day: the overview keeps flat top-5 cards, and the trees only shape the detail-page pivot.

## Page anatomy
1. Tiles: a pace tile that follows the period (1h–24h → daily run rate; 7–90 days and last month → average per day; this month → month-end forecast with the date and daily pace it is based on), AI calls, tokens. Never label a projection as an average. The pace tile's average-per-day and forecast are computed client-side from the totals, the history's `currentCoverage` and the exact `ranges` timestamps — the history's `coveredDays`/`periodDays` are whole-day counts for the tracking-coverage note only, too coarse for sub-day periods.
2. Hero: total for the period, change vs the previous period, line chart (this period solid, previous dashed), metric switch Spend · Calls · Tokens.
3. Bento of cards in three full rows, broad to narrow: spend by source (donut, two columns) · projects / flows · agents · users / providers & keys · models, half the width each. What kind of work spends, then which team, then which flow, agent or person, then which key or model pays. Card rows stay quiet: name and parent on the left, the amount on the right, a thin share bar underneath. The share % is only in the bar's hover tooltip. A bar-behind-the-row layout was tried and dropped on 2026-10-20. Change % lives on the hero, the see-all list and the detail page, not on card rows. There is no "biggest changes" card.
4. The cost footnote.

## Gotchas
- **The usage docs are listed in `docs/docs.json`** (Admin Guide "AI Center" group and API Reference "Usage" group). Edit `docs.json` as text; a JSON re-dump reformats the whole file.
- **There is no list filtered by a parent item.** `/v1/ai-usage/items` only lists a whole dimension for the platform, so a related card on a detail page links to the platform-wide list and says so ("All flows on the platform"). A real "this project's flows" list needs a parent filter on the read API first.
- An item's `name` is `null` for a deleted entity, and also for three sentinel ids that are never real rows: `no-project` (platform-level chat with no project), `activepieces-credits` (the managed-credits "key"), and `unknown-<provider>` (a key that was deleted but still has usage). The UI tells these apart by id, not by a flag — see `usageAdapters.itemDisplayName` in `usage-tab/usage-adapters.ts`.
- A key or model item's `parent` field is never set by the read API (name lookup has no parent column for keys, and models are not looked up by name at all) — their subtitle is the provider's display name instead, reused from `SUPPORTED_AI_PROVIDERS` in `packages/web/src/features/agents/ai-providers.ts`.
- A model's `name` is always the raw `modelId`, never `null` — only project/flow/agent/user/key can show a "Deleted …" name.

## Key files
- `packages/web/src/app/routes/platform/setup/ai/usage-tab` — the page, cards and the API-to-view adapters (`usage-adapters.ts`, `usage-format.ts`).
- `packages/web/src/features/ai-usage` — the read-API client and the `useUsageOverview` / `useUsageItems` / `useUsageDetail` hooks.
- `packages/server/api/src/app/ai/usage/ai-usage-read.service.ts` — the three cached, grouping-sets queries behind the endpoints.
