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

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

### Authorization

Requires `billing:read_usage` permission on the organization.

### Parameters

- `organization_id: str`

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

- `token: Optional[str]`

- `page_size: Optional[int]`

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

- `pagination: Optional[Pagination]`

  - `token: Optional[str]`

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

  - `page_size: Optional[int]`

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

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

    - `"SORT_FIELD_UNSPECIFIED"`

    - `"SORT_FIELD_USAGE"`

    - `"SORT_FIELD_DISPLAY_NAME"`

    - `"SORT_FIELD_BUDGET"`

    - `"SORT_FIELD_BUDGET_USED"`

  - `order: Optional[SortOrder]`

    - `"SORT_ORDER_UNSPECIFIED"`

    - `"SORT_ORDER_ASC"`

    - `"SORT_ORDER_DESC"`

### Returns

- `class UserCreditBudgetUsage: …`

  - `budget_source: Optional[EnterpriseAIUserBudgetPolicySource]`

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

    - `usage_by_type: Optional[List[CreditsByType]]`

      Credits consumed broken down by usage type.

      - `credits: Optional[float]`

      - `usage_type: Optional[UsageType]`

        UsageType identifies the category of usage.

        - `"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]`

      - `currency: Optional[BillingCurrency]`

        - `"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]`

        - `"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]`

    - `usage: Optional[EnterpriseAIUsage]`

    - `usage_by_token_type: Optional[List[EnterpriseAIUsageByTokenType]]`

      - `token_type: Optional[ByokRateCardTokenType]`

      - `usage: Optional[EnterpriseAIUsage]`

  - `user_id: Optional[str]`

  - `utilization_percent: Optional[float]`

### Example

```python
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)
```

#### 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
    }
  ]
}
```