## ListEnterpriseAIUserUsage

`client.Billing.ListEnterpriseAIUserUsage(ctx, params) (*UserUsagePage[UserCostBudgetUsage], error)`

**post** `/gitpod.v1.BillingService/ListEnterpriseAIUserUsage`

Lists enterprise AI usage grouped by user with effective monthly budget data.

Reports BYOK token spend (cost and tokens) for each user and service
account with attributed usage in the date range, including each
subject's effective monthly budget. Usage not attributed to a user or
service account is excluded, so the sum across subjects can be less
than the organization totals from GetEnterpriseAIUsageSummary. The
credits field is not populated by this endpoint.

Budget fields (month_to_date_usage, utilization_percent, over_budget)
are computed from usage inside the requested date range measured
against the monthly limit. Send a range that starts on the first day
of the month for true month-to-date figures.

Use this method to:

- Export per-user BYOK AI spend to external reporting
- Identify the highest spenders in the organization
- Track per-user budget utilization and over-budget users

Only available for enterprise organizations.

### Examples

- List user usage for January:

  Returns per-user BYOK spend with effective budgets, highest spend
  first. Both dates are inclusive and the range must not exceed 31 days.

  ```yaml
  organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
  dateRange:
    startTime: "2024-01-01T00:00:00Z"
    endTime: "2024-01-31T00:00:00Z"
  ```

### Authorization

Requires `billing:read_usage` permission on the organization. Callers
without it can read their own usage by setting filter.subject to
themselves.

### Parameters

- `params BillingListEnterpriseAIUserUsageParams`

  - `DateRange param.Field[DateRange]`

    Body param: Date range for the user usage list. Both start and end dates are inclusive.
    Time-of-day is ignored; dates are truncated to midnight in the specified timezone.

  - `OrganizationID param.Field[string]`

    Body param

  - `Token param.Field[string]`

    Query param

  - `PageSize param.Field[int64]`

    Query param

  - `Filter param.Field[BillingListEnterpriseAIUserUsageParamsFilter]`

    Body param: Optional filter narrowing the returned user usage. When set to a subject,
    the response contains only usage for that user or service account.

    - `Subject Subject`

      Restrict the user usage list to a single subject. The subject must be
      PRINCIPAL_USER or PRINCIPAL_SERVICE_ACCOUNT and belong to the request's
      organization.

      - `ID string`

        id is the UUID of the subject

      - `Principal Principal`

        Principal is the principal of the subject

        - `const PrincipalUnspecified Principal = "PRINCIPAL_UNSPECIFIED"`

        - `const PrincipalAccount Principal = "PRINCIPAL_ACCOUNT"`

        - `const PrincipalUser Principal = "PRINCIPAL_USER"`

        - `const PrincipalRunner Principal = "PRINCIPAL_RUNNER"`

        - `const PrincipalEnvironment Principal = "PRINCIPAL_ENVIRONMENT"`

        - `const PrincipalServiceAccount Principal = "PRINCIPAL_SERVICE_ACCOUNT"`

        - `const PrincipalRunnerManager Principal = "PRINCIPAL_RUNNER_MANAGER"`

  - `Pagination param.Field[BillingListEnterpriseAIUserUsageParamsPagination]`

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

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

    - `Field BillingListEnterpriseAIUserUsageParamsSortField`

      - `const BillingListEnterpriseAIUserUsageParamsSortFieldSortFieldUnspecified BillingListEnterpriseAIUserUsageParamsSortField = "SORT_FIELD_UNSPECIFIED"`

      - `const BillingListEnterpriseAIUserUsageParamsSortFieldSortFieldUsage BillingListEnterpriseAIUserUsageParamsSortField = "SORT_FIELD_USAGE"`

      - `const BillingListEnterpriseAIUserUsageParamsSortFieldSortFieldDisplayName BillingListEnterpriseAIUserUsageParamsSortField = "SORT_FIELD_DISPLAY_NAME"`

      - `const BillingListEnterpriseAIUserUsageParamsSortFieldSortFieldBudget BillingListEnterpriseAIUserUsageParamsSortField = "SORT_FIELD_BUDGET"`

      - `const BillingListEnterpriseAIUserUsageParamsSortFieldSortFieldBudgetUsed BillingListEnterpriseAIUserUsageParamsSortField = "SORT_FIELD_BUDGET_USED"`

    - `Order SortOrder`

      - `const SortOrderUnspecified SortOrder = "SORT_ORDER_UNSPECIFIED"`

      - `const SortOrderAsc SortOrder = "SORT_ORDER_ASC"`

      - `const SortOrderDesc SortOrder = "SORT_ORDER_DESC"`

  - `Timezone param.Field[string]`

    Body param: IANA timezone name used to bucket usage. When empty, defaults to "UTC".

### Returns

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

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

  - `DisplayName string`

  - `IsServiceAccount bool`

  - `MonthlyCostLimitMicrounits string`

  - `MonthToDateUsage EnterpriseAIUsage`

    Usage within the requested date range. Reflects true month-to-date
    usage when the range starts on the first day of the month.

    - `CostMicrounits string`

    - `Credits float64`

    - `Currency BillingCurrency`

    - `Tokens EnterpriseAITokenUsage`

      - `CacheTokens string`

      - `InputTokens string`

      - `OutputTokens string`

      - `TotalTokens string`

  - `NoCap bool`

  - `OverBudget bool`

  - `UserID string`

  - `UtilizationPercent float64`

### Example

```go
package main

import (
  "context"
  "fmt"
  "time"

  "github.com/gitpod-io/gitpod-sdk-go"
  "github.com/gitpod-io/gitpod-sdk-go/option"
  "github.com/gitpod-io/gitpod-sdk-go/shared"
)

func main() {
  client := gitpod.NewClient(
    option.WithBearerToken("My Bearer Token"),
  )
  page, err := client.Billing.ListEnterpriseAIUserUsage(context.TODO(), gitpod.BillingListEnterpriseAIUserUsageParams{
    DateRange: gitpod.F(shared.DateRangeParam{
      EndTime: gitpod.F(time.Now()),
      StartTime: gitpod.F(time.Now()),
    }),
    OrganizationID: gitpod.F("b0e12f6c-4c67-429d-a4a6-d9838b5da047"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}
```

#### Response

```json
{
  "calculatedAt": "2019-12-27T18:11:19.117Z",
  "pagination": {
    "nextToken": "nextToken"
  },
  "totalCount": 0,
  "userUsage": [
    {
      "budgetSource": "ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_UNSPECIFIED",
      "currency": "BILLING_CURRENCY_UNSPECIFIED",
      "displayName": "displayName",
      "isServiceAccount": true,
      "monthlyCostLimitMicrounits": "monthlyCostLimitMicrounits",
      "monthToDateUsage": {
        "costMicrounits": "costMicrounits",
        "credits": 0,
        "currency": "BILLING_CURRENCY_UNSPECIFIED",
        "tokens": {
          "cacheTokens": "cacheTokens",
          "inputTokens": "inputTokens",
          "outputTokens": "outputTokens",
          "totalTokens": "totalTokens"
        }
      },
      "noCap": true,
      "overBudget": true,
      "userId": "userId",
      "utilizationPercent": 0
    }
  ]
}
```