> ## 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 Team Usage > Lists enterprise AI usage grouped by team. `Unary` ยท [`Billing`](/docs/api-reference/generated/billing/overview) Lists enterprise AI usage grouped by team. Reports BYOK token spend per team (cost and tokens) with each team's monthly budget when one applies. The credits field is not populated by this endpoint. Use this method to: * Compare BYOK AI spend across teams * Track team budget utilization * Filter usage to specific teams Only available for enterprise organizations. ### Examples * List team usage for January: Returns BYOK spend per team with monthly budgets. 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. ## Endpoint ```text theme={null} POST /api/gitpod.v1.BillingService/ListEnterpriseAITeamUsage ``` 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/ListEnterpriseAITeamUsage" \ --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.ListEnterpriseAITeamUsageRequest( 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_team_usage(request) print(response) ``` ```typescript TypeScript theme={null} import { create } from "@bufbuild/protobuf"; import { createClientFromEnv } from "@gitpod/sdk"; import { ListEnterpriseAITeamUsageRequestSchema } from "@gitpod/sdk/gitpod/v1/billing_pb"; import { timestampFromDate } from "@bufbuild/protobuf/wkt"; async function main() { const ona = createClientFromEnv(); const request = create(ListEnterpriseAITeamUsageRequestSchema, { 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.listEnterpriseAITeamUsage(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.ListEnterpriseAITeamUsageRequest{ OrganizationId: "", DateRange: &gitpodpb.DateRange{ StartTime: ×tamppb.Timestamp{Seconds: 1767225600}, EndTime: ×tamppb.Timestamp{Seconds: 1767225600}, }, }) response, err := ona.Services.Billing.ListEnterpriseAITeamUsage(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.ListEnterpriseAITeamUsageRequest` | 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 team 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`. | | `filter` | [Filter](#type-gitpod-v1-list-enterprise-ai-team-usage-request-filter) | No | | ## Response `gitpod.v1.ListEnterpriseAITeamUsageResponse` | Field | Type | Required | Description | | -------------- | -------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `pagination` | [PaginationResponse](#type-gitpod-v1-pagination-response) | No | | | `teamUsage` | array of [TeamEnterpriseAIUsage](#type-gitpod-v1-team-enterprise-ai-usage) | No | | | `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.EnterpriseAIUsageBudget` | Field | Type | Required | Description | | ---------------------------- | ---------------------------------------------------------------------------------- | -------- | ----------------------------------------------------- | | `source` | [EnterpriseAIUsageBudgetSource](#enum-gitpod-v1-enterprise-ai-usage-budget-source) | No | Constraints: `enum.defined_only=true, enum.not_in=0`. | | `monthlyCreditLimit` | 64-bit integer string | No | Constraints: `int64.gte=0`. | | `monthlyCostLimitMicrounits` | 64-bit integer string | No | Constraints: `int64.gte=0`. | | `currency` | [BillingCurrency](#enum-gitpod-v1-billing-currency) | No | Constraints: `enum.defined_only=true`. | | `monthToDateUsage` | EnterpriseAIUsage | No | | | `utilizationPercent` | number | No | Constraints: `double.gte=0`. | `gitpod.v1.EnterpriseAIUsageByTokenType` | Field | Type | Required | Description | | ----------- | ------------------------------------------------------------------ | -------- | ----------------------------------------------------- | | `tokenType` | [BYOKRateCardTokenType](#enum-gitpod-v1-byok-rate-card-token-type) | No | Constraints: `enum.defined_only=true, enum.not_in=0`. | | `usage` | EnterpriseAIUsage | No | | `gitpod.v1.ListEnterpriseAITeamUsageRequest.Filter` | Field | Type | Required | Description | | --------- | --------------- | -------- | ----------------------------------------------------------------------- | | `teamIds` | array of string | No | Constraints: `repeated.items.string.uuid=true, repeated.max_items=100`. | `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.TeamEnterpriseAIUsage` | Field | Type | Required | Description | | ------------------ | ------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------ | | `teamId` | string | No | Constraints: `string.uuid=true`. | | `displayName` | string | No | | | `usage` | [EnterpriseAIUsage](#type-gitpod-v1-enterprise-ai-usage) | No | | | `budget` | [EnterpriseAIUsageBudget](#type-gitpod-v1-enterprise-ai-usage-budget) | No | budget is unset when no monthly budget applies to this team. | | `usageByTokenType` | array of [EnterpriseAIUsageByTokenType](#type-gitpod-v1-enterprise-ai-usage-by-token-type) | No | | | Value | Number | Description | | --------------------------------------- | -----: | ----------- | | `BYOK_RATE_CARD_TOKEN_TYPE_UNSPECIFIED` | 0 | | | `BYOK_RATE_CARD_TOKEN_TYPE_INPUT` | 1 | | | `BYOK_RATE_CARD_TOKEN_TYPE_OUTPUT` | 2 | | | `BYOK_RATE_CARD_TOKEN_TYPE_CACHE_READ` | 3 | | | `BYOK_RATE_CARD_TOKEN_TYPE_CACHE_WRITE` | 4 | | | Value | Number | Description | | ------------------------------ | -----: | ----------- | | `BILLING_CURRENCY_UNSPECIFIED` | 0 | | | `BILLING_CURRENCY_USD` | 1 | | | `BILLING_CURRENCY_EUR` | 2 | | | `BILLING_CURRENCY_GBP` | 3 | | | Value | Number | Description | | ------------------------------------------------ | -----: | ----------- | | `ENTERPRISE_AI_USAGE_BUDGET_SOURCE_UNSPECIFIED` | 0 | | | `ENTERPRISE_AI_USAGE_BUDGET_SOURCE_ORGANIZATION` | 1 | | | `ENTERPRISE_AI_USAGE_BUDGET_SOURCE_TEAM` | 2 | |