ListEnterpriseUserCreditUsage

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.

Query ParametersExpand Collapse

token: optional string

pageSize: optional number

maximum100

minimum0

Body ParametersJSONExpand Collapse

organizationId: string

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

formatuuid

asOf: optional string

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

formatdate-time

pagination: optional object { token, pageSize }

token: optional string

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

pageSize: optional number

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

formatint32

maximum100

sort: optional object { field, order }

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

field: optional "SORT_FIELD_UNSPECIFIED" or "SORT_FIELD_USAGE" or "SORT_FIELD_DISPLAY_NAME" or 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

pagination: optional object { nextToken }

nextToken: optional string

Token passed for retrieving the next set of results. Empty if there are no more results

totalCount: optional number

Total number of users with usage in the billing period, across all pages.

formatint32

userUsage: optional array of UserCreditBudgetUsage { budgetSource, creditBudget, displayName, 7 more }

Per-user month-to-date usage with effective monthly budget comparison. Ordered according to the request’s sort field, defaulting to total credits descending.

budgetSource: 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"

creditBudget: optional string

displayName: optional string

isServiceAccount: optional boolean

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: optional CumulativeCreditUsage { totalCredits, usageByType }

CumulativeCreditUsage contains cumulative credit consumption totals.

totalCredits: optional number

Total credits consumed.

formatdouble

usageByType: optional array of CreditsByType { credits, usageType }

Credits consumed broken down by usage type.

credits: optional number

formatdouble

usageType: optional UsageType

UsageType identifies the category of usage.

One of the following:

"USAGE_TYPE_UNSPECIFIED"

"USAGE_TYPE_ENVIRONMENT"

"USAGE_TYPE_AGENTIC"

noCap: optional boolean

overBudget: optional boolean

usageByModel: optional array of EnterpriseAIUsageByModel { model, unpricedUsage, unpricedUsageByTokenType, 2 more }

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

model: optional string

unpricedUsage: optional EnterpriseAIUsage { costMicrounits, credits, currency, tokens }

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

costMicrounits: optional string

credits: optional number

formatdouble

currency: optional BillingCurrency

One of the following:

"BILLING_CURRENCY_UNSPECIFIED"

"BILLING_CURRENCY_USD"

"BILLING_CURRENCY_EUR"

"BILLING_CURRENCY_GBP"

tokens: optional EnterpriseAITokenUsage { cacheTokens, inputTokens, outputTokens, totalTokens }

cacheTokens: optional string

inputTokens: optional string

outputTokens: optional string

totalTokens: optional string

unpricedUsageByTokenType: optional array of EnterpriseAIUsageByTokenType { tokenType, usage }

tokenType: 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 { costMicrounits, credits, currency, tokens }

costMicrounits: optional string

credits: optional number

formatdouble

currency: optional BillingCurrency

One of the following:

"BILLING_CURRENCY_UNSPECIFIED"

"BILLING_CURRENCY_USD"

"BILLING_CURRENCY_EUR"

"BILLING_CURRENCY_GBP"

tokens: optional EnterpriseAITokenUsage { cacheTokens, inputTokens, outputTokens, totalTokens }

cacheTokens: optional string

inputTokens: optional string

outputTokens: optional string

totalTokens: optional string

usage: optional EnterpriseAIUsage { costMicrounits, credits, currency, tokens }

costMicrounits: optional string

credits: optional number

formatdouble

currency: optional BillingCurrency

One of the following:

"BILLING_CURRENCY_UNSPECIFIED"

"BILLING_CURRENCY_USD"

"BILLING_CURRENCY_EUR"

"BILLING_CURRENCY_GBP"

tokens: optional EnterpriseAITokenUsage { cacheTokens, inputTokens, outputTokens, totalTokens }

cacheTokens: optional string

inputTokens: optional string

outputTokens: optional string

totalTokens: optional string

usageByTokenType: optional array of EnterpriseAIUsageByTokenType { tokenType, usage }

tokenType: 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 { costMicrounits, credits, currency, tokens }

costMicrounits: optional string

credits: optional number

formatdouble

currency: optional BillingCurrency

One of the following:

"BILLING_CURRENCY_UNSPECIFIED"

"BILLING_CURRENCY_USD"

"BILLING_CURRENCY_EUR"

"BILLING_CURRENCY_GBP"

tokens: optional EnterpriseAITokenUsage { cacheTokens, inputTokens, outputTokens, totalTokens }

cacheTokens: optional string

inputTokens: optional string

outputTokens: optional string

totalTokens: optional string

userId: optional string

utilizationPercent: optional number

formatdouble

ListEnterpriseUserCreditUsage

curl https://app.gitpod.io/api/gitpod.v1.BillingService/ListEnterpriseUserCreditUsage \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{
          "organizationId": "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
        }'

{
  "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
    }
  ]
}