Skip to content

feat: add per-organization breakdown to user AI spend - #32202

Open
SasSwart wants to merge 3 commits into
mainfrom
aigov-766/user-spend-org-breakdown
Open

SasSwart wants to merge 3 commits into
mainfrom
aigov-766/user-spend-org-breakdown

Conversation

@SasSwart

@SasSwart SasSwart commented Nov 14, 2026 •

Copy link
Copy Markdown
Collaborator

GET /api/v2/users/{user}/ai/spend now returns the user's AI spend per organization, so the avatar menu can show spend for users who belong to more than one organization.

The change is additive. The existing top-level fields stay resolved across all of the user's organizations, and are now hidden from callers who can't read the organization they come from (see below). Two fields are new:

  • organization_id: the organization of the top-level effective group. It is null when no group resolves. The frontend uses it to preselect that organization, so a user in several organizations first sees the same numbers as today.
  • organizations: one entry per organization the user belongs to and the caller can read, sorted by name. Each entry has the effective group, budget, and current-period spend resolved inside that organization, the same way AI Gateway resolves a request made there.

A new query, GetUserAISpendByEffectiveGroupsSince, reads the spend for all of the organizations at once, so the handler makes one spend query rather than one per organization. It reads existing tables, so there's no migration. dbauthz checks it the same way as GetUserAISpendSince: the caller must be able to read the user.

The budget and spend queries only check that the caller can read the user, so the handler limits what it reports to organizations the caller can read:

  • It lists organizations with the caller's own permissions, so organizations holds only those.
  • It reports the top-level fields only when the top-level group is in that list, and takes the spend from the matching entry instead of a second query. Otherwise they stay empty.

Before this PR, an organization-scoped admin could see the top-level group, budget, and spend of a user's other organization through this endpoint. Now they can't. Users reading their own spend, and site-wide admins, see the same top-level values as before.

Also in this PR:

  • cost-controls.md no longer says the effective group is deployment-wide. It now explains the top-level group and the per-organization breakdown.
  • Three Storybook fixtures typed as UserAISpendStatus gain the new fields so the type check passes.

Refs AIGOV-766

🤖 Generated with Claude Code

SasSwart and others added 3 commits November 14, 2026 06:44
GET /api/v2/users/{user}/ai/spend now returns organization_id, the
organization of the top-level effective group, and organizations, the
effective group, budget and current-period spend in each live
organization the user belongs to, sorted by name.

Spend for all organizations is read with one new query,
GetUserAISpendByEffectiveGroupsSince. The organization list uses the
system context because the other queries authorize on the user, and a
caller-scoped list hides organizations from organization-scoped admins.

Refs AIGOV-766

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The per-organization breakdown listed the user's organizations with the
system context. The budget and spend queries only check that the caller
can read the user, so an organization-scoped admin could see the budget
and spend of the user's other organizations. List organizations as the
caller so the breakdown only includes organizations the caller can read.

Refs AIGOV-766

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The top-level effective group is resolved across all of the user's
organizations, and its queries only check that the caller can read the
user. An organization-scoped admin could therefore see the group,
budget, spend, and now organization_id of another organization.

Report the top-level fields only when the group is in the caller-visible
per-organization breakdown, and take its spend from that entry instead
of a second query.

Refs AIGOV-766

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@SasSwart
SasSwart temporarily deployed to main November 14, 2026 12:46 — with GitHub Actions Inactive
@linear-code

linear-code Bot commented Nov 14, 2026

Copy link
Copy Markdown

AIGOV-766

@github-actions

Copy link
Copy Markdown
Contributor

Docs preview

Links open this pull request's preview at https://pr-32202.docs.cdr-preview.dev, which updates with each push.

Check off each page once it's been reviewed. If a page changes in a later push, its checkbox clears automatically so it gets a fresh look. Pages not yet wired into the docs navigation aren't listed here.

Preview sites for each built commit (1)

Every built commit keeps its own preview, newest first. Previews aren't indexed by search engines and are deleted when this pull request is merged or closed.

@SasSwart SasSwart left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Self Review

-- Total spend for user_id per effective group in @effective_group_ids on or
-- after period_start until NOW. Groups with no spend return 0. The
-- period_start parameter is normalized to its UTC calendar day.
SELECT

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

put this through an explain and link the results.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ai_user_daily_spend has its primary key on (user_id, effective_group_id, day), so I'd expect the join to use it. An EXPLAIN would confirm.

@SasSwart
SasSwart temporarily deployed to main November 14, 2026 15:48 — with GitHub Actions Inactive
@SasSwart
SasSwart marked this pull request as ready for review November 16, 2026 08:18
@SasSwart
SasSwart temporarily deployed to main November 16, 2026 08:18 — with GitHub Actions Inactive

@mollymaefraser mollymaefraser left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only had praise/Qs/nits, so going to approve 👍

// so it can land in an organization the caller cannot read. Report it only
// when its group is in the caller-visible breakdown, which also already
// holds its spend for the period.
if entry, found := findOrganizationAISpendByGroup(resp.Organizations, effectiveGroup.GroupID); ok && found {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch on org admins being able to see another org's group, budget and spend through this endpoint. The RoleAccess test makes it clear.

entries := make([]codersdk.UserOrganizationAISpend, 0, len(orgs))
groupIDs := make([]uuid.UUID, 0, len(orgs))
for _, org := range orgs {
group, ok, err := budget.ResolveUserEffectiveGroup(ctx, api.Database, userID, uuid.NullUUID{UUID: org.ID, Valid: true}, budgetPolicy)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice that each org entry uses ResolveUserEffectiveGroup with the org ID, the same as cost.go does when recording a request. The breakdown matches what AI Gateway actually charges.

// so it can land in an organization the caller cannot read. Report it only
// when its group is in the caller-visible breakdown, which also already
// holds its spend for the period.
if entry, found := findOrganizationAISpendByGroup(resp.Organizations, effectiveGroup.GroupID); ok && found {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For an org admin, the top-level fields are now null and current_spend_micros is 0 when the group is in another org. Is anything (frontend or API users) relying on them always being set?

AND effective_group_id = @effective_group_id
AND day >= ((@period_start::timestamptz) AT TIME ZONE 'UTC')::date;

-- name: GetUserAISpendByEffectiveGroupsSince :many

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: could GetUserAISpendByEffectiveGroupsSince get a querier_test.go test like TestGetUserAISpendSince, for example groups with no spend returning 0, and the start-of-period boundary?"

-- Total spend for user_id per effective group in @effective_group_ids on or
-- after period_start until NOW. Groups with no spend return 0. The
-- period_start parameter is normalized to its UTC calendar day.
SELECT

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ai_user_daily_spend has its primary key on (user_id, effective_group_id, day), so I'd expect the join to use it. An EXPLAIN would confirm.

entries := make([]codersdk.UserOrganizationAISpend, 0, len(orgs))
groupIDs := make([]uuid.UUID, 0, len(orgs))
for _, org := range orgs {
group, ok, err := budget.ResolveUserEffectiveGroup(ctx, api.Database, userID, uuid.NullUUID{UUID: org.ID, Valid: true}, budgetPolicy)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: this does about three budget queries per org, plus three for the site-wide group. Fine for a few orgs. Is a user in many orgs realistic?

@DanielleMaywood DanielleMaywood left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

was tagged as agents-frontend code owner and changes to agents page looks fine 👍

// the user. Listing organizations as the caller is what keeps an
// organization-scoped admin from seeing the budget and spend of the user's
// other organizations.
orgs, err := api.Database.GetOrganizationsByUserID(ctx, database.GetOrganizationsByUserIDParams{

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since the endpoint returns all organizations, two users with different org permissions can get a different response for the same user, because the response depends on who's asking. For example, an org admin only sees the organizations they can read, and the top-level effective group is empty when its organization is one they can't read. This seems a bit off 🤔

AFAIK this doesn't follow the patterns we have in the codebase. For example, workspace quota moved from a user-level route to a per-org one.

Should we keep /users/{user}/ai/spend as is, resolving the site-wide effective group (and make that more explicit in the API docs if it isn't yet), and add a separate per-org endpoint, /organizations/{organization}/members/{user}/ai/spend? That way, authorization is simpler, coming from the existing org and member middleware, and the response is the same for every caller who can read the organization. Wdyt?

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As discussed internally, given that the UI needs all orgs and to avoid making multiple requests, a better option might be to keep users/{user}/ai/spend as is, and introduce a new one specific for organizations, e.g., users/{user}/ai/spend/organizations

This branch was previously deployed

2 inactive deployments
main — 4db8bd3b Deployed Nov 16, 2026 by SasSwart via cla #257781
docs-preview — 4db8bd3b Deployed Nov 14, 2026 by SasSwart via deploy #189
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants