> ## 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 User Credit Usage
> Lists per-user month-to-date credit usage with effective monthly budgets.
`Unary` ยท [`Billing`](/docs/api-reference/generated/billing/overview)
Lists per-user month-to-date credit usage with effective monthly budgets.
Results are ordered by total credits descending so the highest spenders
appear first, with user\_id as a stable tiebreaker. Use cursor pagination
to walk the full set for large organizations.
The default SORT\_FIELD\_USAGE ordering supports cursor pagination over any
number of users. Sorting by display name, budget, or budget utilization
computes the order in memory and is limited to organizations with at most
10,000 users; beyond that, use SORT\_FIELD\_USAGE. Because month-to-date
figures are recomputed per request, hold a date range stable across a
paginated walk to keep page tokens valid.
Use this method to:
* Export per-user credit usage to external reporting
* Identify the highest spenders in the organization
* Track per-user budget utilization and over-budget users
### Examples
* List user usage for the current month:
```yaml theme={null}
organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
pagination:
pageSize: 50
```
### Authorization
Requires `billing:read_usage` permission on the organization.
## Endpoint
```text theme={null}
POST /api/gitpod.v1.BillingService/ListEnterpriseUserCreditUsage
```
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/ListEnterpriseUserCreditUsage" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"organizationId": ""
}'
```
```python Python theme={null}
import gitpod.v1.billing_pb2 as billing_pb2
from ona_sdk import create_client_from_env
ona = create_client_from_env()
request = billing_pb2.ListEnterpriseUserCreditUsageRequest(
organization_id="",
)
response = ona.services.billing.list_enterprise_user_credit_usage(request)
print(response)
```
```typescript TypeScript theme={null}
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { ListEnterpriseUserCreditUsageRequestSchema } from "@gitpod/sdk/gitpod/v1/billing_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(ListEnterpriseUserCreditUsageRequestSchema, {
organizationId: "",
});
const response = await ona.services.billing.listEnterpriseUserCreditUsage(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"
)
func main() {
ona, err := sdk.NewFromEnv()
if err != nil {
log.Fatal(err)
}
request := connect.NewRequest(&gitpodpb.ListEnterpriseUserCreditUsageRequest{
OrganizationId: "",
})
response, err := ona.Services.Billing.ListEnterpriseUserCreditUsage(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
```
```json Request body theme={null}
{
"organizationId": ""
}
```
## Request
`gitpod.v1.ListEnterpriseUserCreditUsageRequest`
| Field | Type | Required | Description |
| ---------------- | ---------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `pagination` | [PaginationRequest](#type-gitpod-v1-pagination-request) | No | |
| `organizationId` | string | Yes | organization\_id is the ID of the organization to list user credit usage for. Constraints: `required=true, string.uuid=true`. |
| `asOf` | RFC 3339 timestamp | No | as\_of is the point in time to compute month-to-date usage up to. Defaults to now if not set. |
| `sort` | [Sort](#type-gitpod-v1-list-enterprise-user-credit-usage-request-sort) | No | sort controls the ordering of results. Defaults to total credits descending. |
## Response
`gitpod.v1.ListEnterpriseUserCreditUsageResponse`
| Field | Type | Required | Description |
| ------------ | -------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userUsage` | array of [UserCreditBudgetUsage](#type-gitpod-v1-user-credit-budget-usage) | No | Per-user month-to-date usage with effective monthly budget comparison. Ordered according to the request's sort field, defaulting to total credits descending. |
| `pagination` | [PaginationResponse](#type-gitpod-v1-pagination-response) | No | |
| `totalCount` | integer | No | Total number of users with usage in the billing period, across all pages. |
## Related types
CumulativeCreditUsage contains cumulative credit consumption totals.
`gitpod.v1.CumulativeCreditUsage`
| Field | Type | Required | Description |
| -------------- | ---------------------- | -------- | ------------------------------------------- |
| `totalCredits` | number | No | Total credits consumed. |
| `usageByType` | array of CreditsByType | No | Credits consumed broken down by usage type. |
`gitpod.v1.EnterpriseAIUsageByModel`
| Field | Type | Required | Description |
| -------------------------- | ------------------------------------- | -------- | ----------------------------------------------------------------------- |
| `model` | string | No | |
| `usage` | EnterpriseAIUsage | No | |
| `usageByTokenType` | array of EnterpriseAIUsageByTokenType | No | |
| `unpricedUsage` | EnterpriseAIUsage | No | Usage excluded from spend because no matching BYOK rate was configured. |
| `unpricedUsageByTokenType` | array of EnterpriseAIUsageByTokenType | No | |
`gitpod.v1.ListEnterpriseUserCreditUsageRequest.Sort`
| Field | Type | Required | Description |
| ------- | --------------------------------------------------------------------------------- | -------- | ----------- |
| `field` | [SortField](#enum-gitpod-v1-list-enterprise-user-credit-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.UserCreditBudgetUsage`
| Field | Type | Required | Description |
| -------------------- | --------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `userId` | string | No | |
| `displayName` | string | No | |
| `monthToDateUsage` | [CumulativeCreditUsage](#type-gitpod-v1-cumulative-credit-usage) | No | |
| `creditBudget` | 64-bit integer string | No | |
| `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 | True when user\_id refers to a service account rather than a human user. The dashboard uses this to mark non-human accounts in admin tables. |
| `usageByModel` | array of [EnterpriseAIUsageByModel](#type-gitpod-v1-enterprise-ai-usage-by-model) | No | Month-to-date intelligence usage broken down by model. |
| 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 credits consumed. |
| `SORT_FIELD_DISPLAY_NAME` | 2 | Sort by display name. |
| `SORT_FIELD_BUDGET` | 3 | Sort by effective credit 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 |
| ------------------------ | -----: | ----------- |
| `SORT_ORDER_UNSPECIFIED` | 0 | |
| `SORT_ORDER_ASC` | 1 | |
| `SORT_ORDER_DESC` | 2 | |