Skip to content

feat: list organization AI spend by user - #29129

Merged
ibetitsmike merged 5 commits into
mike/ai-spend-sdkfrom
mike/ai-spend-api
Sep 17, 2026
Merged

ibetitsmike merged 5 commits into
mike/ai-spend-sdkfrom
mike/ai-spend-api

Conversation

@ibetitsmike

@ibetitsmike ibetitsmike commented Sep 9, 2026 •

Copy link
Copy Markdown
Collaborator

Third of a four-PR stack that reworks the AI spend page onto the released organization spend export, GET /api/v2/organizations/{organization}/ai/spend/export, and a sibling per-user endpoint, GET /api/v2/organizations/{organization}/ai/spend/users, instead of the deployment-wide /api/v2/ai-gateway/spend/* endpoints this stack previously proposed. Every PR in the stack was rewritten in place from current main; the head branch name predates the rework. The export's accounting rules are unchanged: token usage by created_at in [period_start, period_end), attributed to the organization through the effective budget group, so the page reconciles with the CSV and with daily budget accounting.

Adds GET /api/v2/organizations/{organization}/ai/spend/users, a paginated per-user report beside the CSV export. It accepts the export's period parameters and the optional provider_name, model, and client filters (client matches after COALESCE(client, 'Unknown'), as the AI Gateway sessions listing does), and it authorizes identically through ResourceGroupMember in the organization. The response is OrganizationAISpendReport: the applied period bounds, retention_start when retention is enabled (so the page can bound its date picker), the user count, a totals object over every matching user, and one page of users (limit default 10, max 100; offset >= 0), each with cost, unpriced usage count, providers, and clients. Each user row also lists the sorted distinct models they spent through (e73049f, added on request after the review round).

The period rules (provided together, at most 31 days, within retention, default narrowed to retention) are shared with the export through the caller's query parser. As a result the export now rejects unknown query parameters whether or not a period is given; previously the excess-parameter check only ran in the explicit-period branch. The export's parameters and output are otherwise unchanged; the CSV itself is not filterable.

The JSON rows are per user while the CSV keeps its user x group x provider x model grain. That is deliberate: the page is the only JSON consumer, and an explicit group_by can be added later without changing this contract. A page past the last user still carries the window totals, read from the first page.

Query cost, measured on PostgreSQL 13 with 400k token usages and 200k interceptions across 4 organizations (31-day window of about 52k usages for the target organization): ListOrganizationAISpendUsers 128 ms unfiltered and 68 ms filtered by provider. Token usage is read through the existing partial index on (effective_group_id, created_at); no new index is needed. The provider and client aggregates were added after this measurement.

Tests cover pagination validation (including the export rejecting page parameters), report contents and filters against the CSV, retention narrowing and rejection, retention disabled, and the role matrix (Owner, User Admin, Auditor, Org Admin, Org User Admin OK; member 403; other organization 404).

Previous revisions served this report from the export endpoint through Accept negotiation and also added the dimension filters to the CSV export (#29220, #29224); the separate endpoint replaces the former, and the CSV filters were dropped because the page does not use them.

Xum prepared this PR on behalf of @ibetitsmike.

Codex on e73049f: P2 on the moving now - retention lower bound for clients that echo the default window while paging. Declined: it is the released CSV export's contract, the report echoes retention_start, and the page never echoes the default window; the handler and tests now use OrganizationAISpendPage (8cdc127).

@github-actions

github-actions Bot commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

Docs preview

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.

@ibetitsmike
ibetitsmike added this pull request to stack #29130 September 9, 2026 11:49
@ibetitsmike ibetitsmike changed the title mike/ai spend api feat: add AI Gateway spend queries and endpoints Sep 9, 2026
@ibetitsmike
ibetitsmike force-pushed the mike/ai-spend-api branch 3 times, most recently from 57e6569 to c337295 Compare September 11, 2026 09:35
@ibetitsmike
ibetitsmike removed this pull request from stack #29130 September 11, 2026 09:46
@ibetitsmike
ibetitsmike changed the base branch from main to mike/ai-spend-endpoint-users September 11, 2026 09:46
@ibetitsmike ibetitsmike changed the title feat: add AI Gateway spend queries and endpoints feat: add AI Gateway spend summary endpoints Sep 11, 2026
@ibetitsmike
ibetitsmike marked this pull request as ready for review September 11, 2026 11:31
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 11, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review 🔄 Running since 2026-09-17T04:31:19.859262Z 8cdc127 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@coderagents

coderagents Bot commented Sep 11, 2026

Copy link
Copy Markdown
Contributor

Documentation Check

Updates Needed

  • docs/ai-coder/ai-gateway/cost-controls.md - The "Spend reporting" section describes spend reporting (dashboard + CSV export) but does not mention the two new AI Gateway spend endpoints added in this PR. Add a note that AI Gateway spend is also available as per-deployment and per-user summaries with per-provider, per-model, and per-client breakdowns, each capped at the 100 most expensive entries, available through Get AI Gateway spend summary for the deployment and Get AI Gateway spend summary for a user API endpoints.

New Documentation Needed

  • docs/ai-coder/ai-governance.md - The "Measure AI adoption and spend" section lists AI Gateway usage metrics conceptually; consider pointing readers to the spend reporting surfaces documented in Cost Control so the deployment/user spend summaries are surfaced conceptually, not only in the API reference.

Automated review via Coder Agents

@ibetitsmike
ibetitsmike marked this pull request as draft September 15, 2026 18:48
@ibetitsmike
ibetitsmike removed this pull request from stack #29225 September 15, 2026 18:49
@ibetitsmike ibetitsmike changed the title feat: add AI Gateway spend summary endpoints feat: serve the organization AI spend export as paginated JSON Sep 15, 2026
@ibetitsmike

Copy link
Copy Markdown
Collaborator Author

This PR was reworked in place on 2026-09-15: the stack now extends the released organization spend export (GET /api/v2/organizations/{organization}/ai/spend/export) with filters and an Accept: application/json per-user report instead of adding /api/v2/ai-gateway/spend/* endpoints, and the page shows one organization's total and per-user cost only. The description above reflects the new content; earlier review threads refer to code that no longer exists on this branch. #29222 (session counts) was closed because it has no counterpart.

@codex review

Xum posted this comment on behalf of @ibetitsmike.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5ee43cdc7e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread enterprise/coderd/aibridge.go Resolved
Comment thread enterprise/coderd/aibridge.go Resolved
Comment thread enterprise/coderd/aibridge.go Resolved

@ssncferreira ssncferreira 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.

LGTM 👍

Comment thread enterprise/coderd/aibridge.go Resolved
Comment thread enterprise/coderd/aibridge.go Resolved
Comment thread enterprise/coderd/aibridge_test.go Resolved
Comment thread enterprise/coderd/aibridge_test.go Resolved
Comment thread enterprise/coderd/aibridge_test.go Resolved
@ibetitsmike

Copy link
Copy Markdown
Collaborator Author

Pushed fixes for the human review round (period validation switch, Swagger description, test moves, combined filter case, totals object).

@codex review

Xum posted this comment on behalf of @ibetitsmike.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: 62011b2698

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@ibetitsmike

Copy link
Copy Markdown
Collaborator Author

Pushed the models field through the users endpoint and regenerated the API docs (e73049f); restacked.

@codex review

Xum posted this comment on behalf of @ibetitsmike.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e73049fb80

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread enterprise/coderd/aibridge.go Resolved
Adds GET /api/v2/organizations/{organization}/ai/spend/users, a paginated
per-user report built from the same token usage as the CSV export, with
optional provider_name, model, and client filters. Each user lists the
providers and clients they spent through, and the report echoes the
applied period and the start of the retention window so clients can bound
their date pickers.

The period parsing is shared with the export through the caller's query
parser, so both endpoints now reject unknown query parameters whether or
not a period is given.
…n object

Fill the report's totals object and regenerate the API reference.
Separate the default, half-specified, and explicit period cases in a
switch again, keeping the shared parameter validation ahead of it. Move
the export's unknown page parameter case beside the other export period
validation cases, cover a combined dimension filter, and reword the filter
description.
The organization AI spend users endpoint returns each user's sorted
models next to providers and clients, with the API docs regenerated.
…nd users

Follows the codersdk change: the handler and its tests use
OrganizationAISpendPage, which cannot carry an unsupported cursor.
@ibetitsmike

Copy link
Copy Markdown
Collaborator Author

Restacked on the SDK page type (8cdc127); the retention-boundary thread is answered above.

@codex review

Xum posted this comment on behalf of @ibetitsmike.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Swish!

Reviewed commit: 8cdc127dcb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@ibetitsmike
ibetitsmike marked this pull request as ready for review September 17, 2026 04:31
@ibetitsmike
ibetitsmike merged commit 9d97337 into main Sep 17, 2026
48 of 69 checks passed
@ibetitsmike
ibetitsmike deleted the mike/ai-spend-api branch September 17, 2026 04:32
@github-actions github-actions Bot locked and limited conversation to collaborators Sep 17, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants