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

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

### Authorization

Requires `billing:read_usage` permission on the organization.

### Query Parameters

- `token: optional string`

- `pageSize: optional number`

### Body Parameters

- `organizationId: string`

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

- `asOf: optional string`

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

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

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

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

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

- `userUsage: optional array of UserCreditBudgetUsage`

  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`

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

    CumulativeCreditUsage contains cumulative credit consumption totals.

    - `totalCredits: optional number`

      Total credits consumed.

    - `usageByType: optional array of CreditsByType`

      Credits consumed broken down by usage type.

      - `credits: optional number`

      - `usageType: optional UsageType`

        UsageType identifies the category of usage.

        - `"USAGE_TYPE_UNSPECIFIED"`

        - `"USAGE_TYPE_ENVIRONMENT"`

        - `"USAGE_TYPE_AGENTIC"`

  - `noCap: optional boolean`

  - `overBudget: optional boolean`

  - `usageByModel: optional array of EnterpriseAIUsageByModel`

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

    - `model: optional string`

    - `unpricedUsage: optional EnterpriseAIUsage`

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

      - `costMicrounits: optional string`

      - `credits: optional number`

      - `currency: optional BillingCurrency`

        - `"BILLING_CURRENCY_UNSPECIFIED"`

        - `"BILLING_CURRENCY_USD"`

        - `"BILLING_CURRENCY_EUR"`

        - `"BILLING_CURRENCY_GBP"`

      - `tokens: optional EnterpriseAITokenUsage`

        - `cacheTokens: optional string`

        - `inputTokens: optional string`

        - `outputTokens: optional string`

        - `totalTokens: optional string`

    - `unpricedUsageByTokenType: optional array of EnterpriseAIUsageByTokenType`

      - `tokenType: 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`

    - `usageByTokenType: optional array of EnterpriseAIUsageByTokenType`

      - `tokenType: optional ByokRateCardTokenType`

      - `usage: optional EnterpriseAIUsage`

  - `userId: optional string`

  - `utilizationPercent: optional number`

### Example

```http
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"
        }'
```

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