> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List Enterprise AI User Usage
> Lists enterprise AI usage grouped by user with effective monthly budget data.
`Unary` ยท [`Billing`](/docs/api-reference/generated/billing/overview)
Lists enterprise AI usage grouped by user with effective monthly budget data.
Reports BYOK token spend (cost and tokens) for each user and service
account with attributed usage in the date range, including each
subject's effective monthly budget. Usage not attributed to a user or
service account is excluded, so the sum across subjects can be less
than the organization totals from GetEnterpriseAIUsageSummary. The
credits field is not populated by this endpoint.
Budget fields (month\_to\_date\_usage, utilization\_percent, over\_budget)
are computed from usage inside the requested date range measured
against the monthly limit. Send a range that starts on the first day
of the month for true month-to-date figures.
Use this method to:
* Export per-user BYOK AI spend to external reporting
* Identify the highest spenders in the organization
* Track per-user budget utilization and over-budget users
Only available for enterprise organizations.
### Examples
* List user usage for January:
Returns per-user BYOK spend with effective budgets, highest spend
first. Both dates are inclusive and the range must not exceed 31 days.
```yaml theme={null}
organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
dateRange:
startTime: "2024-01-01T00:00:00Z"
endTime: "2024-01-31T00:00:00Z"
```
### Authorization
Requires `billing:read_usage` permission on the organization. Callers
without it can read their own usage by setting filter.subject to
themselves.
## Endpoint
```text theme={null}
POST /api/gitpod.v1.BillingService/ListEnterpriseAIUserUsage
```
Send a Bearer token as described in [Authentication](/docs/api-reference#authenticate-requests). If your organization uses a custom management-plane domain, replace `https://app.ona.com` with that domain.
## Request example
```bash cURL theme={null}
export ONA_HOST=https://app.ona.com
export ONA_API_KEY=
curl --request POST \
--url "$ONA_HOST/api/gitpod.v1.BillingService/ListEnterpriseAIUserUsage" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"dateRange": {
"endTime": "2026-01-01T00:00:00Z",
"startTime": "2026-01-01T00:00:00Z"
},
"organizationId": ""
}'
```
```python Python theme={null}
import gitpod.v1.billing_pb2 as billing_pb2
import gitpod.v1.usage_pb2 as usage_pb2
import google.protobuf.timestamp_pb2 as timestamp_pb2
from ona_sdk import create_client_from_env
ona = create_client_from_env()
request = billing_pb2.ListEnterpriseAIUserUsageRequest(
organization_id="",
date_range=usage_pb2.DateRange(
start_time=timestamp_pb2.Timestamp(seconds=1767225600),
end_time=timestamp_pb2.Timestamp(seconds=1767225600),
),
)
response = ona.services.billing.list_enterprise_ai_user_usage(request)
print(response)
```
```typescript TypeScript theme={null}
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { ListEnterpriseAIUserUsageRequestSchema } from "@gitpod/sdk/gitpod/v1/billing_pb";
import { timestampFromDate } from "@bufbuild/protobuf/wkt";
async function main() {
const ona = createClientFromEnv();
const request = create(ListEnterpriseAIUserUsageRequestSchema, {
organizationId: "",
dateRange: {
startTime: timestampFromDate(new Date("2026-01-01T00:00:00Z")),
endTime: timestampFromDate(new Date("2026-01-01T00:00:00Z")),
},
});
const response = await ona.services.billing.listEnterpriseAIUserUsage(request);
console.log(response);
}
main().catch(console.error);
```
```go Go theme={null}
package main
import (
"context"
"fmt"
"log"
"connectrpc.com/connect"
"github.com/gitpod-io/gitpod-sdk-go/sdk"
gitpodpb "github.com/gitpod-io/gitpod-sdk-go/v1"
timestamppb "google.golang.org/protobuf/types/known/timestamppb"
)
func main() {
ona, err := sdk.NewFromEnv()
if err != nil {
log.Fatal(err)
}
request := connect.NewRequest(&gitpodpb.ListEnterpriseAIUserUsageRequest{
OrganizationId: "",
DateRange: &gitpodpb.DateRange{
StartTime: ×tamppb.Timestamp{Seconds: 1767225600},
EndTime: ×tamppb.Timestamp{Seconds: 1767225600},
},
})
response, err := ona.Services.Billing.ListEnterpriseAIUserUsage(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
```
```json Request body theme={null}
{
"dateRange": {
"endTime": "2026-01-01T00:00:00Z",
"startTime": "2026-01-01T00:00:00Z"
},
"organizationId": ""
}
```
## Request
`gitpod.v1.ListEnterpriseAIUserUsageRequest`
| Field | Type | Required | Description |
| ---------------- | ---------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pagination` | [PaginationRequest](#type-gitpod-v1-pagination-request) | No | |
| `organizationId` | string | Yes | Constraints: `required=true, string.uuid=true`. |
| `dateRange` | [DateRange](#type-gitpod-v1-date-range) | Yes | Date range for the user usage list. Both start and end dates are inclusive. Time-of-day is ignored; dates are truncated to midnight in the specified timezone. Constraints: `required=true`. |
| `timezone` | string | No | IANA timezone name used to bucket usage. When empty, defaults to "UTC". Constraints: `string.max_len=64`. |
| `sort` | [Sort](#type-gitpod-v1-list-enterprise-ai-user-usage-request-sort) | No | sort controls the ordering of results. Defaults to total spend descending. |
| `filter` | [Filter](#type-gitpod-v1-list-enterprise-ai-user-usage-request-filter) | No | Optional filter narrowing the returned user usage. When set to a subject, the response contains only usage for that user or service account. |
## Response
`gitpod.v1.ListEnterpriseAIUserUsageResponse`
| Field | Type | Required | Description |
| -------------- | ---------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `pagination` | [PaginationResponse](#type-gitpod-v1-pagination-response) | No | |
| `userUsage` | array of [UserCostBudgetUsage](#type-gitpod-v1-user-cost-budget-usage) | No | |
| `totalCount` | integer | No | Total number of users with usage in the billing period, across all pages. |
| `calculatedAt` | RFC 3339 timestamp | No | calculated\_at is the time through which usage has been calculated. Usage after this timestamp may still be processing. |
## Related types
DateRange specifies a time period for queries.
`gitpod.v1.DateRange`
| Field | Type | Required | Description |
| ----------- | ------------------ | -------- | ----------------------------------------------------------------------- |
| `startTime` | RFC 3339 timestamp | Yes | Start time of the date range (inclusive). Constraints: `required=true`. |
| `endTime` | RFC 3339 timestamp | Yes | End time of the date range (exclusive). Constraints: `required=true`. |
`gitpod.v1.EnterpriseAIUsage`
| Field | Type | Required | Description |
| ---------------- | --------------------------------------------------- | -------- | -------------------------------------- |
| `credits` | number | No | Constraints: `double.gte=0`. |
| `costMicrounits` | 64-bit integer string | No | Constraints: `int64.gte=0`. |
| `currency` | [BillingCurrency](#enum-gitpod-v1-billing-currency) | No | Constraints: `enum.defined_only=true`. |
| `tokens` | EnterpriseAITokenUsage | No | |
`gitpod.v1.ListEnterpriseAIUserUsageRequest.Filter`
| Field | Type | Required | Description |
| --------- | ---------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subject` | [Subject](#type-gitpod-v1-subject) | No | Restrict the user usage list to a single subject. The subject must be PRINCIPAL\_USER or PRINCIPAL\_SERVICE\_ACCOUNT and belong to the request's organization. |
`gitpod.v1.ListEnterpriseAIUserUsageRequest.Sort`
| Field | Type | Required | Description |
| ------- | ----------------------------------------------------------------------------- | -------- | ----------- |
| `field` | [SortField](#enum-gitpod-v1-list-enterprise-ai-user-usage-request-sort-field) | No | |
| `order` | [SortOrder](#enum-gitpod-v1-sort-order) | No | |
`gitpod.v1.PaginationRequest`
| Field | Type | Required | Description |
| ---------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `pageSize` | integer | No | Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100. Constraints: `int32.gte=0, int32.lte=100`. |
| `token` | string | No | Token for the next set of results that was returned as next\_token of a PaginationResponse |
`gitpod.v1.PaginationResponse`
| Field | Type | Required | Description |
| ----------- | ------ | -------- | --------------------------------------------------------------------------------------- |
| `nextToken` | string | No | Token passed for retrieving the next set of results. Empty if there are no more results |
`gitpod.v1.Subject`
| Field | Type | Required | Description |
| ----------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------- |
| `id` | string | No | id is the UUID of the subject Constraints: `ignore=1, string.uuid=true`. |
| `principal` | [Principal](#enum-gitpod-v1-principal) | No | Principal is the principal of the subject Constraints: `enum.defined_only=true`. |
`gitpod.v1.UserCostBudgetUsage`
| Field | Type | Required | Description |
| ---------------------------- | --------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `userId` | string | No | |
| `displayName` | string | No | |
| `monthToDateUsage` | [EnterpriseAIUsage](#type-gitpod-v1-enterprise-ai-usage) | No | Usage within the requested date range. Reflects true month-to-date usage when the range starts on the first day of the month. |
| `monthlyCostLimitMicrounits` | 64-bit integer string | No | Constraints: `int64.gte=0`. |
| `currency` | [BillingCurrency](#enum-gitpod-v1-billing-currency) | No | Constraints: `enum.defined_only=true`. |
| `budgetSource` | [EnterpriseAIUserBudgetPolicySource](#enum-gitpod-v1-enterprise-ai-user-budget-policy-source) | No | Constraints: `enum.defined_only=true`. |
| `noCap` | boolean | No | |
| `utilizationPercent` | number | No | |
| `overBudget` | boolean | No | |
| `isServiceAccount` | boolean | No | |
| Value | Number | Description |
| ------------------------------ | -----: | ----------- |
| `BILLING_CURRENCY_UNSPECIFIED` | 0 | |
| `BILLING_CURRENCY_USD` | 1 | |
| `BILLING_CURRENCY_EUR` | 2 | |
| `BILLING_CURRENCY_GBP` | 3 | |
| Value | Number | Description |
| ------------------------------------------------------ | -----: | ----------- |
| `ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_UNSPECIFIED` | 0 | |
| `ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_NONE` | 1 | |
| `ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_ORGANIZATION` | 2 | |
| `ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_USER` | 3 | |
| Value | Number | Description |
| ------------------------- | -----: | ------------------------------------------------------------------------- |
| `SORT_FIELD_UNSPECIFIED` | 0 | |
| `SORT_FIELD_USAGE` | 1 | Sort by month-to-date total spend. |
| `SORT_FIELD_DISPLAY_NAME` | 2 | Sort by display name. |
| `SORT_FIELD_BUDGET` | 3 | Sort by effective monthly cost budget (users without a budget sort last). |
| `SORT_FIELD_BUDGET_USED` | 4 | Sort by budget utilization percentage (users without a budget sort last). |
| Value | Number | Description |
| --------------------------- | -----: | ----------- |
| `PRINCIPAL_UNSPECIFIED` | 0 | |
| `PRINCIPAL_ACCOUNT` | 1 | |
| `PRINCIPAL_USER` | 2 | |
| `PRINCIPAL_RUNNER` | 3 | |
| `PRINCIPAL_ENVIRONMENT` | 4 | |
| `PRINCIPAL_SERVICE_ACCOUNT` | 5 | |
| `PRINCIPAL_RUNNER_MANAGER` | 6 | |
| Value | Number | Description |
| ------------------------ | -----: | ----------- |
| `SORT_ORDER_UNSPECIFIED` | 0 | |
| `SORT_ORDER_ASC` | 1 | |
| `SORT_ORDER_DESC` | 2 | |