ListEnterpriseUserCreditUsage

client.Billing.ListEnterpriseUserCreditUsage(ctx, params) (*UserUsagePage[UserCreditBudgetUsage], error)

POST/gitpod.v1.BillingService/ListEnterpriseUserCreditUsage

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.

ParametersExpand Collapse

params BillingListEnterpriseUserCreditUsageParams

OrganizationID param.Field[string]

Body param: organization_id is the ID of the organization to list user credit usage for.

formatuuid

Token param.Field[string]Optional

Query param

PageSize param.Field[int64]Optional

Query param

maximum100

minimum0

AsOf param.Field[Time]Optional

Body param: as_of is the point in time to compute month-to-date usage up to. Defaults to now if not set.

formatdate-time

Pagination param.Field[BillingListEnterpriseUserCreditUsageParamsPagination]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[BillingListEnterpriseUserCreditUsageParamsSort]Optional

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

Field BillingListEnterpriseUserCreditUsageParamsSortFieldOptional

One of the following:

const BillingListEnterpriseUserCreditUsageParamsSortFieldSortFieldUnspecified BillingListEnterpriseUserCreditUsageParamsSortField = "SORT_FIELD_UNSPECIFIED"

const BillingListEnterpriseUserCreditUsageParamsSortFieldSortFieldUsage BillingListEnterpriseUserCreditUsageParamsSortField = "SORT_FIELD_USAGE"

const BillingListEnterpriseUserCreditUsageParamsSortFieldSortFieldDisplayName BillingListEnterpriseUserCreditUsageParamsSortField = "SORT_FIELD_DISPLAY_NAME"

const BillingListEnterpriseUserCreditUsageParamsSortFieldSortFieldBudget BillingListEnterpriseUserCreditUsageParamsSortField = "SORT_FIELD_BUDGET"

const BillingListEnterpriseUserCreditUsageParamsSortFieldSortFieldBudgetUsed BillingListEnterpriseUserCreditUsageParamsSortField = "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"

ReturnsExpand Collapse

type UserCreditBudgetUsage 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"

CreditBudget stringOptional

DisplayName stringOptional

IsServiceAccount boolOptional

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.

MonthToDateUsage CumulativeCreditUsageOptional

CumulativeCreditUsage contains cumulative credit consumption totals.

TotalCredits float64Optional

Total credits consumed.

formatdouble

UsageByType []CreditsByTypeOptional

Credits consumed broken down by usage type.

Credits float64Optional

formatdouble

UsageType UsageTypeOptional

UsageType identifies the category of usage.

One of the following:

const UsageTypeUnspecified UsageType = "USAGE_TYPE_UNSPECIFIED"

const UsageTypeEnvironment UsageType = "USAGE_TYPE_ENVIRONMENT"

const UsageTypeAgentic UsageType = "USAGE_TYPE_AGENTIC"

NoCap boolOptional

OverBudget boolOptional

UsageByModel []EnterpriseAIUsageByModelOptional

Month-to-date intelligence usage broken down by model.

Model stringOptional

UnpricedUsage EnterpriseAIUsageOptional

Usage excluded from spend because no matching BYOK rate was configured.

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

UnpricedUsageByTokenType []EnterpriseAIUsageByTokenTypeOptional

TokenType ByokRateCardTokenTypeOptional

One of the following:

const ByokRateCardTokenTypeUnspecified ByokRateCardTokenType = "BYOK_RATE_CARD_TOKEN_TYPE_UNSPECIFIED"

const ByokRateCardTokenTypeInput ByokRateCardTokenType = "BYOK_RATE_CARD_TOKEN_TYPE_INPUT"

const ByokRateCardTokenTypeOutput ByokRateCardTokenType = "BYOK_RATE_CARD_TOKEN_TYPE_OUTPUT"

const ByokRateCardTokenTypeCacheRead ByokRateCardTokenType = "BYOK_RATE_CARD_TOKEN_TYPE_CACHE_READ"

const ByokRateCardTokenTypeCacheWrite ByokRateCardTokenType = "BYOK_RATE_CARD_TOKEN_TYPE_CACHE_WRITE"

Usage EnterpriseAIUsageOptional

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

Usage EnterpriseAIUsageOptional

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

UsageByTokenType []EnterpriseAIUsageByTokenTypeOptional

TokenType ByokRateCardTokenTypeOptional

One of the following:

const ByokRateCardTokenTypeUnspecified ByokRateCardTokenType = "BYOK_RATE_CARD_TOKEN_TYPE_UNSPECIFIED"

const ByokRateCardTokenTypeInput ByokRateCardTokenType = "BYOK_RATE_CARD_TOKEN_TYPE_INPUT"

const ByokRateCardTokenTypeOutput ByokRateCardTokenType = "BYOK_RATE_CARD_TOKEN_TYPE_OUTPUT"

const ByokRateCardTokenTypeCacheRead ByokRateCardTokenType = "BYOK_RATE_CARD_TOKEN_TYPE_CACHE_READ"

const ByokRateCardTokenTypeCacheWrite ByokRateCardTokenType = "BYOK_RATE_CARD_TOKEN_TYPE_CACHE_WRITE"

Usage EnterpriseAIUsageOptional

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

UserID stringOptional

UtilizationPercent float64Optional

formatdouble

ListEnterpriseUserCreditUsage

package main

import (
  "context"
  "fmt"

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

func main() {
  client := gitpod.NewClient(
    option.WithBearerToken("My Bearer Token"),
  )
  page, err := client.Billing.ListEnterpriseUserCreditUsage(context.TODO(), gitpod.BillingListEnterpriseUserCreditUsageParams{
    OrganizationID: gitpod.F("b0e12f6c-4c67-429d-a4a6-d9838b5da047"),
    Pagination: gitpod.F(gitpod.BillingListEnterpriseUserCreditUsageParamsPagination{
      PageSize: gitpod.F(int64(50)),
    }),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}

{
  "pagination": {
    "nextToken": "nextToken"
  },
  "totalCount": 0,
  "userUsage": [
    {
      "budgetSource": "ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_UNSPECIFIED",
      "creditBudget": "creditBudget",
      "displayName": "displayName",
      "isServiceAccount": true,
      "monthToDateUsage": {
        "totalCredits": 0,
        "usageByType": [
          {
            "credits": 0,
            "usageType": "USAGE_TYPE_UNSPECIFIED"
          }
        ]
      },
      "noCap": true,
      "overBudget": true,
      "usageByModel": [
        {
          "model": "model",
          "unpricedUsage": {
            "costMicrounits": "costMicrounits",
            "credits": 0,
            "currency": "BILLING_CURRENCY_UNSPECIFIED",
            "tokens": {
              "cacheTokens": "cacheTokens",
              "inputTokens": "inputTokens",
              "outputTokens": "outputTokens",
              "totalTokens": "totalTokens"
            }
          },
          "unpricedUsageByTokenType": [
            {
              "tokenType": "BYOK_RATE_CARD_TOKEN_TYPE_UNSPECIFIED",
              "usage": {
                "costMicrounits": "costMicrounits",
                "credits": 0,
                "currency": "BILLING_CURRENCY_UNSPECIFIED",
                "tokens": {
                  "cacheTokens": "cacheTokens",
                  "inputTokens": "inputTokens",
                  "outputTokens": "outputTokens",
                  "totalTokens": "totalTokens"
                }
              }
            }
          ],
          "usage": {
            "costMicrounits": "costMicrounits",
            "credits": 0,
            "currency": "BILLING_CURRENCY_UNSPECIFIED",
            "tokens": {
              "cacheTokens": "cacheTokens",
              "inputTokens": "inputTokens",
              "outputTokens": "outputTokens",
              "totalTokens": "totalTokens"
            }
          },
          "usageByTokenType": [
            {
              "tokenType": "BYOK_RATE_CARD_TOKEN_TYPE_UNSPECIFIED",
              "usage": {
                "costMicrounits": "costMicrounits",
                "credits": 0,
                "currency": "BILLING_CURRENCY_UNSPECIFIED",
                "tokens": {
                  "cacheTokens": "cacheTokens",
                  "inputTokens": "inputTokens",
                  "outputTokens": "outputTokens",
                  "totalTokens": "totalTokens"
                }
              }
            }
          ]
        }
      ],
      "userId": "userId",
      "utilizationPercent": 0
    }
  ]
}

Returns Examples

{
  "pagination": {
    "nextToken": "nextToken"
  },
  "totalCount": 0,
  "userUsage": [
    {
      "budgetSource": "ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_UNSPECIFIED",
      "creditBudget": "creditBudget",
      "displayName": "displayName",
      "isServiceAccount": true,
      "monthToDateUsage": {
        "totalCredits": 0,
        "usageByType": [
          {
            "credits": 0,
            "usageType": "USAGE_TYPE_UNSPECIFIED"
          }
        ]
      },
      "noCap": true,
      "overBudget": true,
      "usageByModel": [
        {
          "model": "model",
          "unpricedUsage": {
            "costMicrounits": "costMicrounits",
            "credits": 0,
            "currency": "BILLING_CURRENCY_UNSPECIFIED",
            "tokens": {
              "cacheTokens": "cacheTokens",
              "inputTokens": "inputTokens",
              "outputTokens": "outputTokens",
              "totalTokens": "totalTokens"
            }
          },
          "unpricedUsageByTokenType": [
            {
              "tokenType": "BYOK_RATE_CARD_TOKEN_TYPE_UNSPECIFIED",
              "usage": {
                "costMicrounits": "costMicrounits",
                "credits": 0,
                "currency": "BILLING_CURRENCY_UNSPECIFIED",
                "tokens": {
                  "cacheTokens": "cacheTokens",
                  "inputTokens": "inputTokens",
                  "outputTokens": "outputTokens",
                  "totalTokens": "totalTokens"
                }
              }
            }
          ],
          "usage": {
            "costMicrounits": "costMicrounits",
            "credits": 0,
            "currency": "BILLING_CURRENCY_UNSPECIFIED",
            "tokens": {
              "cacheTokens": "cacheTokens",
              "inputTokens": "inputTokens",
              "outputTokens": "outputTokens",
              "totalTokens": "totalTokens"
            }
          },
          "usageByTokenType": [
            {
              "tokenType": "BYOK_RATE_CARD_TOKEN_TYPE_UNSPECIFIED",
              "usage": {
                "costMicrounits": "costMicrounits",
                "credits": 0,
                "currency": "BILLING_CURRENCY_UNSPECIFIED",
                "tokens": {
                  "cacheTokens": "cacheTokens",
                  "inputTokens": "inputTokens",
                  "outputTokens": "outputTokens",
                  "totalTokens": "totalTokens"
                }
              }
            }
          ]
        }
      ],
      "userId": "userId",
      "utilizationPercent": 0
    }
  ]
}