ListEnterpriseAIUserUsage

client.Billing.ListEnterpriseAIUserUsage(ctx, params) (*UserUsagePage[UserCostBudgetUsage], error)

POST/gitpod.v1.BillingService/ListEnterpriseAIUserUsage

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.

ParametersExpand Collapse

params BillingListEnterpriseAIUserUsageParams

DateRange param.Field[DateRange]

Body param: 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.

OrganizationID param.Field[string]

Body param

formatuuid

Token param.Field[string]Optional

Query param

PageSize param.Field[int64]Optional

Query param

maximum100

minimum0

Filter param.Field[BillingListEnterpriseAIUserUsageParamsFilter]Optional

Body param: Optional filter narrowing the returned user usage. When set to a subject, the response contains only usage for that user or service account.

Subject SubjectOptional

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.

ID stringOptional

id is the UUID of the subject

formatuuid

Principal PrincipalOptional

Principal is the principal of the subject

One of the following:

const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"

const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"

const PrincipalUser Principal = "PRINCIPAL_USER"

const PrincipalRunner Principal = "PRINCIPAL_RUNNER"

const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"

const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"

const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"

Pagination param.Field[BillingListEnterpriseAIUserUsageParamsPagination]Optional

Body param

Token stringOptional

Token for the next set of results that was returned as next_token of a PaginationResponse

PageSize int64Optional

Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100.

formatint32

maximum100

Sort param.Field[BillingListEnterpriseAIUserUsageParamsSort]Optional

Body param: sort controls the ordering of results. Defaults to total spend descending.

Field BillingListEnterpriseAIUserUsageParamsSortFieldOptional

One of the following:

const BillingListEnterpriseAIUserUsageParamsSortFieldSortFieldUnspecified BillingListEnterpriseAIUserUsageParamsSortField = "SORT_FIELD_UNSPECIFIED"

const BillingListEnterpriseAIUserUsageParamsSortFieldSortFieldUsage BillingListEnterpriseAIUserUsageParamsSortField = "SORT_FIELD_USAGE"

const BillingListEnterpriseAIUserUsageParamsSortFieldSortFieldDisplayName BillingListEnterpriseAIUserUsageParamsSortField = "SORT_FIELD_DISPLAY_NAME"

const BillingListEnterpriseAIUserUsageParamsSortFieldSortFieldBudget BillingListEnterpriseAIUserUsageParamsSortField = "SORT_FIELD_BUDGET"

const BillingListEnterpriseAIUserUsageParamsSortFieldSortFieldBudgetUsed BillingListEnterpriseAIUserUsageParamsSortField = "SORT_FIELD_BUDGET_USED"

Order SortOrderOptional

One of the following:

const SortOrderUnspecified SortOrder = "SORT_ORDER_UNSPECIFIED"

const SortOrderAsc SortOrder = "SORT_ORDER_ASC"

const SortOrderDesc SortOrder = "SORT_ORDER_DESC"

Timezone param.Field[string]Optional

Body param: IANA timezone name used to bucket usage. When empty, defaults to “UTC”.

maxLength64

ReturnsExpand Collapse

type UserCostBudgetUsage struct{…}

BudgetSource EnterpriseAIUserBudgetPolicySourceOptional

One of the following:

const EnterpriseAIUserBudgetPolicySourceUnspecified EnterpriseAIUserBudgetPolicySource = "ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_UNSPECIFIED"

const EnterpriseAIUserBudgetPolicySourceNone EnterpriseAIUserBudgetPolicySource = "ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_NONE"

const EnterpriseAIUserBudgetPolicySourceOrganization EnterpriseAIUserBudgetPolicySource = "ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_ORGANIZATION"

const EnterpriseAIUserBudgetPolicySourceUser EnterpriseAIUserBudgetPolicySource = "ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_USER"

Currency BillingCurrencyOptional

One of the following:

const BillingCurrencyUnspecified BillingCurrency = "BILLING_CURRENCY_UNSPECIFIED"

const BillingCurrencyUsd BillingCurrency = "BILLING_CURRENCY_USD"

const BillingCurrencyEur BillingCurrency = "BILLING_CURRENCY_EUR"

const BillingCurrencyGbp BillingCurrency = "BILLING_CURRENCY_GBP"

DisplayName stringOptional

IsServiceAccount boolOptional

MonthlyCostLimitMicrounits stringOptional

MonthToDateUsage EnterpriseAIUsageOptional

Usage within the requested date range. Reflects true month-to-date usage when the range starts on the first day of the month.

CostMicrounits stringOptional

Credits float64Optional

formatdouble

Currency BillingCurrencyOptional

One of the following:

const BillingCurrencyUnspecified BillingCurrency = "BILLING_CURRENCY_UNSPECIFIED"

const BillingCurrencyUsd BillingCurrency = "BILLING_CURRENCY_USD"

const BillingCurrencyEur BillingCurrency = "BILLING_CURRENCY_EUR"

const BillingCurrencyGbp BillingCurrency = "BILLING_CURRENCY_GBP"

Tokens EnterpriseAITokenUsageOptional

CacheTokens stringOptional

InputTokens stringOptional

OutputTokens stringOptional

TotalTokens stringOptional

NoCap boolOptional

OverBudget boolOptional

UserID stringOptional

UtilizationPercent float64Optional

formatdouble

ListEnterpriseAIUserUsage

package main

import (
  "context"
  "fmt"
  "time"

  "github.com/gitpod-io/gitpod-sdk-go"
  "github.com/gitpod-io/gitpod-sdk-go/option"
  "github.com/gitpod-io/gitpod-sdk-go/shared"
)

func main() {
  client := gitpod.NewClient(
    option.WithBearerToken("My Bearer Token"),
  )
  page, err := client.Billing.ListEnterpriseAIUserUsage(context.TODO(), gitpod.BillingListEnterpriseAIUserUsageParams{
    DateRange: gitpod.F(shared.DateRangeParam{
      EndTime: gitpod.F(time.Now()),
      StartTime: gitpod.F(time.Now()),
    }),
    OrganizationID: gitpod.F("b0e12f6c-4c67-429d-a4a6-d9838b5da047"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}

{
  "calculatedAt": "2019-12-27T18:11:19.117Z",
  "pagination": {
    "nextToken": "nextToken"
  },
  "totalCount": 0,
  "userUsage": [
    {
      "budgetSource": "ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_UNSPECIFIED",
      "currency": "BILLING_CURRENCY_UNSPECIFIED",
      "displayName": "displayName",
      "isServiceAccount": true,
      "monthlyCostLimitMicrounits": "monthlyCostLimitMicrounits",
      "monthToDateUsage": {
        "costMicrounits": "costMicrounits",
        "credits": 0,
        "currency": "BILLING_CURRENCY_UNSPECIFIED",
        "tokens": {
          "cacheTokens": "cacheTokens",
          "inputTokens": "inputTokens",
          "outputTokens": "outputTokens",
          "totalTokens": "totalTokens"
        }
      },
      "noCap": true,
      "overBudget": true,
      "userId": "userId",
      "utilizationPercent": 0
    }
  ]
}

Returns Examples

{
  "calculatedAt": "2019-12-27T18:11:19.117Z",
  "pagination": {
    "nextToken": "nextToken"
  },
  "totalCount": 0,
  "userUsage": [
    {
      "budgetSource": "ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_UNSPECIFIED",
      "currency": "BILLING_CURRENCY_UNSPECIFIED",
      "displayName": "displayName",
      "isServiceAccount": true,
      "monthlyCostLimitMicrounits": "monthlyCostLimitMicrounits",
      "monthToDateUsage": {
        "costMicrounits": "costMicrounits",
        "credits": 0,
        "currency": "BILLING_CURRENCY_UNSPECIFIED",
        "tokens": {
          "cacheTokens": "cacheTokens",
          "inputTokens": "inputTokens",
          "outputTokens": "outputTokens",
          "totalTokens": "totalTokens"
        }
      },
      "noCap": true,
      "overBudget": true,
      "userId": "userId",
      "utilizationPercent": 0
    }
  ]
}