## 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:

  ```yaml
  organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
  pagination:
    pageSize: 50
  ```

### Authorization

Requires `billing:read_usage` permission on the organization.

### Parameters

- `params BillingListEnterpriseUserCreditUsageParams`

  - `OrganizationID param.Field[string]`

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

  - `Token param.Field[string]`

    Query param

  - `PageSize param.Field[int64]`

    Query param

  - `AsOf param.Field[Time]`

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

  - `Pagination param.Field[BillingListEnterpriseUserCreditUsageParamsPagination]`

    Body param

    - `Token string`

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

    - `PageSize int64`

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

  - `Sort param.Field[BillingListEnterpriseUserCreditUsageParamsSort]`

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

    - `Field BillingListEnterpriseUserCreditUsageParamsSortField`

      - `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 SortOrder`

      - `const SortOrderUnspecified SortOrder = "SORT_ORDER_UNSPECIFIED"`

      - `const SortOrderAsc SortOrder = "SORT_ORDER_ASC"`

      - `const SortOrderDesc SortOrder = "SORT_ORDER_DESC"`

### Returns

- `type UserCreditBudgetUsage struct{…}`

  - `BudgetSource EnterpriseAIUserBudgetPolicySource`

    - `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 string`

  - `DisplayName string`

  - `IsServiceAccount 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.

  - `MonthToDateUsage CumulativeCreditUsage`

    CumulativeCreditUsage contains cumulative credit consumption totals.

    - `TotalCredits float64`

      Total credits consumed.

    - `UsageByType []CreditsByType`

      Credits consumed broken down by usage type.

      - `Credits float64`

      - `UsageType UsageType`

        UsageType identifies the category of usage.

        - `const UsageTypeUnspecified UsageType = "USAGE_TYPE_UNSPECIFIED"`

        - `const UsageTypeEnvironment UsageType = "USAGE_TYPE_ENVIRONMENT"`

        - `const UsageTypeAgentic UsageType = "USAGE_TYPE_AGENTIC"`

  - `NoCap bool`

  - `OverBudget bool`

  - `UsageByModel []EnterpriseAIUsageByModel`

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

    - `Model string`

    - `UnpricedUsage EnterpriseAIUsage`

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

      - `CostMicrounits string`

      - `Credits float64`

      - `Currency BillingCurrency`

        - `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 EnterpriseAITokenUsage`

        - `CacheTokens string`

        - `InputTokens string`

        - `OutputTokens string`

        - `TotalTokens string`

    - `UnpricedUsageByTokenType []EnterpriseAIUsageByTokenType`

      - `TokenType ByokRateCardTokenType`

        - `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 EnterpriseAIUsage`

    - `Usage EnterpriseAIUsage`

    - `UsageByTokenType []EnterpriseAIUsageByTokenType`

      - `TokenType ByokRateCardTokenType`

      - `Usage EnterpriseAIUsage`

  - `UserID string`

  - `UtilizationPercent float64`

### Example

```go
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)
}
```

#### Response

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