List Enterprise AI User Usage

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

POST /api/gitpod.v1.BillingService/ListEnterpriseAIUserUsage

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/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": "<organization-id>"
}'

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="<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)

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: "<organization-id>",
    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);

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: "<organization-id>",
		DateRange: &gitpodpb.DateRange{
			StartTime: &timestamppb.Timestamp{Seconds: 1767225600},
			EndTime: &timestamppb.Timestamp{Seconds: 1767225600},
		},
	})
	response, err := ona.Services.Billing.ListEnterpriseAIUserUsage(context.Background(), request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response.Msg)
}

{
  "dateRange": {
    "endTime": "2026-01-01T00:00:00Z",
    "startTime": "2026-01-01T00:00:00Z"
  },
  "organizationId": "<organization-id>"
}

Request

gitpod.v1.ListEnterpriseAIUserUsageRequest

Field	Type	Required	Description
`pagination`	PaginationRequest	No
`organizationId`	string	Yes	Constraints: `required=true, string.uuid=true`.
`dateRange`	DateRange	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	No	sort controls the ordering of results. Defaults to total spend descending.
`filter`	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	No
`userUsage`	array of UserCostBudgetUsage	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.

DateRange

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

EnterpriseAIUsage

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	No	Constraints: `enum.defined_only=true`.
`tokens`	EnterpriseAITokenUsage	No

Filter

gitpod.v1.ListEnterpriseAIUserUsageRequest.Filter

Field	Type	Required	Description
`subject`	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.

Sort

gitpod.v1.ListEnterpriseAIUserUsageRequest.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

Subject

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	No	Principal is the principal of the subject Constraints: `enum.defined_only=true`.

UserCostBudgetUsage

gitpod.v1.UserCostBudgetUsage

Field	Type	Required	Description
`userId`	string	No
`displayName`	string	No
`monthToDateUsage`	EnterpriseAIUsage	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	No	Constraints: `enum.defined_only=true`.
`budgetSource`	EnterpriseAIUserBudgetPolicySource	No	Constraints: `enum.defined_only=true`.
`noCap`	boolean	No
`utilizationPercent`	number	No
`overBudget`	boolean	No
`isServiceAccount`	boolean	No

BillingCurrency

Value	Number	Description
`BILLING_CURRENCY_UNSPECIFIED`	0
`BILLING_CURRENCY_USD`	1
`BILLING_CURRENCY_EUR`	2
`BILLING_CURRENCY_GBP`	3

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

Principal

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

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

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