---
title: "List organization AI spend by user"
method: GET
path: "/api/experimental/organizations/{organization}/ai/spend/users"
tags: ["Enterprise"]
---

# List organization AI spend by user

`GET /api/experimental/organizations/{organization}/ai/spend/users`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/experimental/organizations/{organization}/ai/spend/users`
- Auth: API key in header `Coder-Session-Token`

Returns one page of per-user AI spend for the organization, most expensive first, built from the same raw AI Gateway token usage as the CSV export so the two reconcile. Each user lists the providers and clients they spent through, and the response carries the user count, total spend, and unpriced usage count over every matching user.
The optional period_start and period_end query parameters bound the period and are interpreted as UTC. They must be provided together and span at most 31 days. When both are omitted, the current UTC monthly period is used.
An explicit period_start must fall within the configured AI Gateway data retention window, since older token usage is purged. The default period is narrowed to that window instead. The response echoes the applied bounds and, when retention is enabled, the start of the retention window.
The optional provider_name, model, and client query parameters restrict the spend report to usage matching all supplied filters. Use client=Unknown for usage with an unknown or missing client.
Unknown query parameters are rejected.
Requires organization-level administrator permissions.

## Path parameters

- `organization` string, uuid, required

## Query parameters

- `period_start` string, date-time
- `period_end` string, date-time
- `provider_name` string
- `model` string
- `client` string
- `limit` integer
- `offset` integer

## Response `200`

OK

- CodersdkOrganizationAISpendReport
  - `count` integer: Count is the number of users with token usage matching the filter.
  - `period_end` string, date-time: PeriodEnd is the exclusive upper bound of the current budget period.
  - `period_start` string, date-time: PeriodStart is the inclusive lower bound of the current budget period.
  - `retention_start` string, date-time: RetentionStart is the oldest instant for which token usage is still retained. An explicit period must not start before it. Omitted when the deployment does not purge AI Gateway data.
  - `totals` CodersdkOrganizationAISpendTotals
    - `cost_micros` integer: CostMicros is the priced spend of every matching user.
    - `unpriced_usage_count` integer: UnpricedUsageCount is the number of token usage records without a cost across every matching user.
  - `users` CodersdkOrganizationAISpendUser[]: Users is the requested page, most expensive first.
    - `avatar_url` string
    - `clients` string[]: Clients are the clients the user spent through, sorted. Usage without a recorded client is reported as Unknown.
    - `cost_micros` integer: CostMicros is the user's priced spend over the period.
    - `models` string[]: Models are the models the user spent through, sorted.
    - `name` string
    - `providers` string[]: Providers are the configured provider names the user spent through, sorted.
    - `unpriced_usage_count` integer: UnpricedUsageCount is the number of the user's token usage records that carry no cost because their model had no price when they were recorded.
    - `user_id` string, uuid
    - `username` string

## Changes

- **2026-09-25** `061a060d0d35`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/coder/apis/coder-api/changes/api/experimental/organizations/:organization/ai/spend/users/get.md)

---

[API](https://skmtc.dev/coder/apis/coder-api.md) - [All operations](https://skmtc.dev/coder/apis/coder-api/llms.txt) - [OpenAPI document](https://skmtc.dev/coder/apis/coder-api/revisions/4669d93796ab?raw)