## ListEnterpriseAITeamUsage

`client.Billing.ListEnterpriseAITeamUsage(ctx, params) (*TeamUsagePage[TeamEnterpriseAIUsage], error)`

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

Lists enterprise AI usage grouped by team.

Reports BYOK token spend per team (cost and tokens) with each team's
monthly budget when one applies. The credits field is not populated by
this endpoint.

Use this method to:

- Compare BYOK AI spend across teams
- Track team budget utilization
- Filter usage to specific teams

Only available for enterprise organizations.

### Examples

- List team usage for January:

  Returns BYOK spend per team with monthly budgets. 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.

### Parameters

- `params BillingListEnterpriseAITeamUsageParams`

  - `DateRange param.Field[DateRange]`

    Body param: Date range for the team 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[BillingListEnterpriseAITeamUsageParamsFilter]`

    Body param

    - `TeamIDs []string`

  - `Pagination param.Field[BillingListEnterpriseAITeamUsageParamsPagination]`

    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.

  - `Timezone param.Field[string]`

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

### Returns

- `type TeamEnterpriseAIUsage struct{…}`

  - `Budget EnterpriseAIUsageBudget`

    budget is unset when no monthly budget applies to this team.

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

    - `MonthlyCostLimitMicrounits string`

    - `MonthlyCreditLimit string`

    - `MonthToDateUsage EnterpriseAIUsage`

      - `CostMicrounits string`

      - `Credits float64`

      - `Currency BillingCurrency`

      - `Tokens EnterpriseAITokenUsage`

        - `CacheTokens string`

        - `InputTokens string`

        - `OutputTokens string`

        - `TotalTokens string`

    - `Source EnterpriseAIUsageBudgetSource`

      - `const EnterpriseAIUsageBudgetSourceUnspecified EnterpriseAIUsageBudgetSource = "ENTERPRISE_AI_USAGE_BUDGET_SOURCE_UNSPECIFIED"`

      - `const EnterpriseAIUsageBudgetSourceOrganization EnterpriseAIUsageBudgetSource = "ENTERPRISE_AI_USAGE_BUDGET_SOURCE_ORGANIZATION"`

      - `const EnterpriseAIUsageBudgetSourceTeam EnterpriseAIUsageBudgetSource = "ENTERPRISE_AI_USAGE_BUDGET_SOURCE_TEAM"`

    - `UtilizationPercent float64`

  - `DisplayName string`

  - `TeamID string`

  - `Usage EnterpriseAIUsage`

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

### 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.ListEnterpriseAITeamUsage(context.TODO(), gitpod.BillingListEnterpriseAITeamUsageParams{
    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"
  },
  "teamUsage": [
    {
      "budget": {
        "currency": "BILLING_CURRENCY_UNSPECIFIED",
        "monthlyCostLimitMicrounits": "monthlyCostLimitMicrounits",
        "monthlyCreditLimit": "monthlyCreditLimit",
        "monthToDateUsage": {
          "costMicrounits": "costMicrounits",
          "credits": 0,
          "currency": "BILLING_CURRENCY_UNSPECIFIED",
          "tokens": {
            "cacheTokens": "cacheTokens",
            "inputTokens": "inputTokens",
            "outputTokens": "outputTokens",
            "totalTokens": "totalTokens"
          }
        },
        "source": "ENTERPRISE_AI_USAGE_BUDGET_SOURCE_UNSPECIFIED",
        "utilizationPercent": 0
      },
      "displayName": "displayName",
      "teamId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "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"
            }
          }
        }
      ]
    }
  ]
}
```