List Enterprise User Credit Usage

Unary · Billing 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:

organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
pagination:
  pageSize: 50

Authorization

Requires billing:read_usage permission on the organization.

Endpoint

POST /api/gitpod.v1.BillingService/ListEnterpriseUserCreditUsage

Send a Bearer token as described in Authentication. If your organization uses a custom management-plane domain, replace https://app.ona.com with that domain.

Request example

export ONA_HOST=https://app.ona.com
export ONA_API_KEY=<your-token>

curl --request POST \
  --url "$ONA_HOST/api/gitpod.v1.BillingService/ListEnterpriseUserCreditUsage" \
  --header "Authorization: Bearer $ONA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "organizationId": "<organization-id>"
}'

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="<organization-id>",
)
response = ona.services.billing.list_enterprise_user_credit_usage(request)
print(response)

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: "<organization-id>",
  });
  const response = await ona.services.billing.listEnterpriseUserCreditUsage(request);
  console.log(response);
}

main().catch(console.error);

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: "<organization-id>",
	})
	response, err := ona.Services.Billing.ListEnterpriseUserCreditUsage(context.Background(), request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Msg)
}

{
  "organizationId": "<organization-id>"
}

Request

gitpod.v1.ListEnterpriseUserCreditUsageRequest

Field	Type	Required	Description
`pagination`	PaginationRequest	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	No	sort controls the ordering of results. Defaults to total credits descending.

Response

gitpod.v1.ListEnterpriseUserCreditUsageResponse

Field	Type	Required	Description
`userUsage`	array of UserCreditBudgetUsage	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	No
`totalCount`	integer	No	Total number of users with usage in the billing period, across all pages.

CumulativeCreditUsage

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.

EnterpriseAIUsageByModel

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

Sort

gitpod.v1.ListEnterpriseUserCreditUsageRequest.Sort

Field	Type	Required	Description
`field`	SortField	No
`order`	SortOrder	No

PaginationRequest

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

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

UserCreditBudgetUsage

gitpod.v1.UserCreditBudgetUsage

Field	Type	Required	Description
`userId`	string	No
`displayName`	string	No
`monthToDateUsage`	CumulativeCreditUsage	No
`creditBudget`	64-bit integer string	No
`budgetSource`	EnterpriseAIUserBudgetPolicySource	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	No	Month-to-date intelligence usage broken down by model.

EnterpriseAIUserBudgetPolicySource

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

SortField

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).

SortOrder

Value	Number	Description
`SORT_ORDER_UNSPECIFIED`	0
`SORT_ORDER_ASC`	1
`SORT_ORDER_DESC`	2

Get Started

Using Ona

Configuration

Administration & Security

Infrastructure

Billing

Learn

Reference

Support

Releases

List Enterprise User Credit Usage

Examples

Authorization

Endpoint

Request example

Request

Response

​Examples

​Authorization

​Endpoint

​Request example

​Request

​Response

​Related types

Examples

Authorization

Endpoint

Request example

Request

Response

Related types