## GetCreditUsageReport

`client.Billing.GetCreditUsageReport(ctx, body) (*BillingGetCreditUsageReportResponse, error)`

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

Returns a daily credit usage report for an enterprise organization.

Each day reports org-wide credits by usage type, plus per-user, per-team,
per-environment, and per-conversation breakdowns (top consumers with the
remainder aggregated into an "Others" bucket) and a per-model breakdown
of intelligence usage.

Use this method to:

- Chart daily credit consumption over a date range
- Attribute credit usage to users, teams, environments, and conversations
- Restrict the report to a single user or service account

### Examples

- Get the report for January:

  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. A user
without it can read their own usage by setting filter.subject to their
own user identity; this self-access path is not available to service
accounts.

### Parameters

- `body BillingGetCreditUsageReportParams`

  - `DateRange param.Field[DateRange]`

    Date range for the report. Both start and end dates are inclusive.
    Time-of-day is ignored; dates are truncated to midnight in the specified timezone.
    The range must not exceed 31 days.

  - `OrganizationID param.Field[string]`

  - `Filter param.Field[CreditUsageReportFilter]`

    Optional filter narrowing the returned data. When unset or empty, the
    response preserves the default behavior (top-N users + "Others"). See
    CreditUsageReportFilter for per-field response-scoping semantics.

  - `Timezone param.Field[string]`

    IANA timezone name (e.g. "America/New_York", "Europe/Berlin") used to
    bucket daily usage. When empty, defaults to "UTC".

### Returns

- `type BillingGetCreditUsageReportResponse struct{…}`

  - `DailyUsage []DailyCreditUsage`

    One entry per day in the requested date range.

    - `ConversationUsage []AgentExecutionCreditUsage`

      Per-agent-execution usage for this day (top conversations + "Others").
      Empty agent_execution_id represents the "Others" aggregation bucket.

      - `AgentExecutionID string`

        Empty when representing the "Others" aggregation bucket.

      - `DisplayName string`

      - `Usage []CreditsByType`

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

    - `Date Time`

      Start of the day (midnight in the requested timezone).

    - `EnvironmentUsage []EnvironmentCreditUsage`

      Per-environment usage for this day (top environments + "Others").
      Empty environment_id represents the "Others" aggregation bucket.

      - `DisplayName string`

      - `EnvironmentID string`

        Empty when representing the "Others" aggregation bucket.

      - `Usage []CreditsByType`

        - `Credits float64`

        - `UsageType UsageType`

          UsageType identifies the category of usage.

    - `OrgUsage []CreditsByType`

      Org-wide usage broken down by type.

      - `Credits float64`

      - `UsageType UsageType`

        UsageType identifies the category of usage.

    - `TeamUsage []TeamCreditUsage`

      Per-team usage for this day (top teams + "Others").
      Empty team_id represents the "Others" aggregation bucket.

      - `DisplayName string`

      - `TeamID string`

        Empty when representing the "Others" aggregation bucket.

      - `Usage []CreditsByType`

        - `Credits float64`

        - `UsageType UsageType`

          UsageType identifies the category of usage.

    - `UsageByModel []EnterpriseAIUsageByModel`

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

    - `UserUsage []UserCreditUsage`

      Per-user usage for this day (top users + "Others").

      - `DisplayName string`

      - `Usage []CreditsByType`

        - `Credits float64`

        - `UsageType UsageType`

          UsageType identifies the category of usage.

      - `UsageByModel []EnterpriseAIUsageByModel`

        Intelligence usage broken down by model.

        - `Model string`

        - `UnpricedUsage EnterpriseAIUsage`

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

        - `UnpricedUsageByTokenType []EnterpriseAIUsageByTokenType`

        - `Usage EnterpriseAIUsage`

        - `UsageByTokenType []EnterpriseAIUsageByTokenType`

      - `UserID string`

        Empty when representing the "Others" aggregation bucket.

  - `PeriodStart Time`

    Start of the billing period for this organization.
    Used by the frontend to filter out months before usage tracking began.

  - `UpdatedAt Time`

    When the report data was last computed.

### 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"),
  )
  response, err := client.Billing.GetCreditUsageReport(context.TODO(), gitpod.BillingGetCreditUsageReportParams{
    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", response.DailyUsage)
}
```

#### Response

```json
{
  "dailyUsage": [
    {
      "conversationUsage": [
        {
          "agentExecutionId": "agentExecutionId",
          "displayName": "displayName",
          "usage": [
            {
              "credits": 0,
              "usageType": "USAGE_TYPE_UNSPECIFIED"
            }
          ]
        }
      ],
      "date": "2019-12-27T18:11:19.117Z",
      "environmentUsage": [
        {
          "displayName": "displayName",
          "environmentId": "environmentId",
          "usage": [
            {
              "credits": 0,
              "usageType": "USAGE_TYPE_UNSPECIFIED"
            }
          ]
        }
      ],
      "orgUsage": [
        {
          "credits": 0,
          "usageType": "USAGE_TYPE_UNSPECIFIED"
        }
      ],
      "teamUsage": [
        {
          "displayName": "displayName",
          "teamId": "teamId",
          "usage": [
            {
              "credits": 0,
              "usageType": "USAGE_TYPE_UNSPECIFIED"
            }
          ]
        }
      ],
      "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"
                }
              }
            }
          ]
        }
      ],
      "userUsage": [
        {
          "displayName": "displayName",
          "usage": [
            {
              "credits": 0,
              "usageType": "USAGE_TYPE_UNSPECIFIED"
            }
          ],
          "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"
        }
      ]
    }
  ],
  "periodStart": "2019-12-27T18:11:19.117Z",
  "updatedAt": "2019-12-27T18:11:19.117Z"
}
```