Skip to content
Ona API Reference
Ona Docs
API Reference
Billing

ListEnterpriseUserCreditUsage

billing.list_enterprise_user_credit_usage(BillingListEnterpriseUserCreditUsageParams**kwargs) -> SyncUserUsagePage[UserCreditBudgetUsage]
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
organization_id: str

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

formatuuid
token: Optional[str]
page_size: Optional[int]
maximum100
minimum0
as_of: Optional[Union[str, datetime, null]]

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

formatdate-time
sort: Optional[Sort]

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

field: Optional[Literal["SORT_FIELD_UNSPECIFIED", "SORT_FIELD_USAGE", "SORT_FIELD_DISPLAY_NAME", 2 more]]
One of the following:
"SORT_FIELD_UNSPECIFIED"
"SORT_FIELD_USAGE"
"SORT_FIELD_DISPLAY_NAME"
"SORT_FIELD_BUDGET"
"SORT_FIELD_BUDGET_USED"
order: Optional[SortOrder]
One of the following:
"SORT_ORDER_UNSPECIFIED"
"SORT_ORDER_ASC"
"SORT_ORDER_DESC"
ReturnsExpand Collapse
class UserCreditBudgetUsage: …
budget_source: Optional[EnterpriseAIUserBudgetPolicySource]
One of the following:
"ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_UNSPECIFIED"
"ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_NONE"
"ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_ORGANIZATION"
"ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_USER"
credit_budget: Optional[str]
display_name: Optional[str]
is_service_account: Optional[bool]

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.

month_to_date_usage: Optional[CumulativeCreditUsage]

CumulativeCreditUsage contains cumulative credit consumption totals.

total_credits: Optional[float]

Total credits consumed.

formatdouble
usage_by_type: Optional[List[CreditsByType]]

Credits consumed broken down by usage type.

credits: Optional[float]
formatdouble
usage_type: Optional[UsageType]

UsageType identifies the category of usage.

One of the following:
"USAGE_TYPE_UNSPECIFIED"
"USAGE_TYPE_ENVIRONMENT"
"USAGE_TYPE_AGENTIC"
no_cap: Optional[bool]
over_budget: Optional[bool]
usage_by_model: Optional[List[EnterpriseAIUsageByModel]]

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

model: Optional[str]
unpriced_usage: Optional[EnterpriseAIUsage]

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

cost_microunits: Optional[str]
credits: Optional[float]
formatdouble
currency: Optional[BillingCurrency]
One of the following:
"BILLING_CURRENCY_UNSPECIFIED"
"BILLING_CURRENCY_USD"
"BILLING_CURRENCY_EUR"
"BILLING_CURRENCY_GBP"
tokens: Optional[EnterpriseAITokenUsage]
cache_tokens: Optional[str]
input_tokens: Optional[str]
output_tokens: Optional[str]
total_tokens: Optional[str]
unpriced_usage_by_token_type: Optional[List[EnterpriseAIUsageByTokenType]]
token_type: Optional[ByokRateCardTokenType]
One of the following:
"BYOK_RATE_CARD_TOKEN_TYPE_UNSPECIFIED"
"BYOK_RATE_CARD_TOKEN_TYPE_INPUT"
"BYOK_RATE_CARD_TOKEN_TYPE_OUTPUT"
"BYOK_RATE_CARD_TOKEN_TYPE_CACHE_READ"
"BYOK_RATE_CARD_TOKEN_TYPE_CACHE_WRITE"
usage: Optional[EnterpriseAIUsage]
cost_microunits: Optional[str]
credits: Optional[float]
formatdouble
currency: Optional[BillingCurrency]
One of the following:
"BILLING_CURRENCY_UNSPECIFIED"
"BILLING_CURRENCY_USD"
"BILLING_CURRENCY_EUR"
"BILLING_CURRENCY_GBP"
tokens: Optional[EnterpriseAITokenUsage]
cache_tokens: Optional[str]
input_tokens: Optional[str]
output_tokens: Optional[str]
total_tokens: Optional[str]
usage: Optional[EnterpriseAIUsage]
cost_microunits: Optional[str]
credits: Optional[float]
formatdouble
currency: Optional[BillingCurrency]
One of the following:
"BILLING_CURRENCY_UNSPECIFIED"
"BILLING_CURRENCY_USD"
"BILLING_CURRENCY_EUR"
"BILLING_CURRENCY_GBP"
tokens: Optional[EnterpriseAITokenUsage]
cache_tokens: Optional[str]
input_tokens: Optional[str]
output_tokens: Optional[str]
total_tokens: Optional[str]
usage_by_token_type: Optional[List[EnterpriseAIUsageByTokenType]]
token_type: Optional[ByokRateCardTokenType]
One of the following:
"BYOK_RATE_CARD_TOKEN_TYPE_UNSPECIFIED"
"BYOK_RATE_CARD_TOKEN_TYPE_INPUT"
"BYOK_RATE_CARD_TOKEN_TYPE_OUTPUT"
"BYOK_RATE_CARD_TOKEN_TYPE_CACHE_READ"
"BYOK_RATE_CARD_TOKEN_TYPE_CACHE_WRITE"
usage: Optional[EnterpriseAIUsage]
cost_microunits: Optional[str]
credits: Optional[float]
formatdouble
currency: Optional[BillingCurrency]
One of the following:
"BILLING_CURRENCY_UNSPECIFIED"
"BILLING_CURRENCY_USD"
"BILLING_CURRENCY_EUR"
"BILLING_CURRENCY_GBP"
tokens: Optional[EnterpriseAITokenUsage]
cache_tokens: Optional[str]
input_tokens: Optional[str]
output_tokens: Optional[str]
total_tokens: Optional[str]
user_id: Optional[str]
utilization_percent: Optional[float]
formatdouble

ListEnterpriseUserCreditUsage

import os
from gitpod import Gitpod

client = Gitpod(
    bearer_token=os.environ.get("GITPOD_API_KEY"),  # This is the default and can be omitted
)
page = client.billing.list_enterprise_user_credit_usage(
    organization_id="b0e12f6c-4c67-429d-a4a6-d9838b5da047",
    pagination={
        "page_size": 50
    },
)
page = page.user_usage[0]
print(page.budget_source)
{
  "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
    }
  ]
}