## GetCumulativeCreditUsage

`client.Billing.GetCumulativeCreditUsage(ctx, body) (*BillingGetCumulativeCreditUsageResponse, error)`

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

Returns cumulative credit usage for an organization and its teams.

Use this method to:

- Get the total cumulative credit consumption as of a point in time
- Get per-team cumulative usage with credit allocation (budget) comparison
- Display team credit summaries on the usage page and team detail page
- Display user budget utilization when user budgets are enabled

### Examples

- Get current cumulative usage:

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

- Get cumulative usage as of a specific date:

  ```yaml
  organizationId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
  asOf: "2026-03-31T23:59:59Z"
  ```

### Authorization

Requires `billing:read_usage` permission on the organization.

### Parameters

- `body BillingGetCumulativeCreditUsageParams`

  - `OrganizationID param.Field[string]`

    organization_id is the ID of the organization to get cumulative usage for.

  - `AsOf param.Field[Time]`

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

### Returns

- `type BillingGetCumulativeCreditUsageResponse struct{…}`

  - `OrgUsage CumulativeCreditUsage`

    Org-wide cumulative usage, broken down by type and total.

    - `TotalCredits float64`

      Total credits consumed.

    - `UsageByType []CreditsByType`

      Credits consumed broken down by usage type.

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

  - `PeriodStart Time`

    Start of the cumulative calculation period.
    Cumulative totals are computed from this date forward.

  - `TeamUsage []TeamCumulativeCreditUsage`

    Per-team cumulative usage with credit allocation comparison.
    Returns all teams (no top-N limit).

    - `CreditBudget string`

      The team's credit allocation (budget) in whole credits, if set.
      Not set means no allocation has been configured for this team.

    - `DisplayName string`

    - `TeamID string`

    - `Usage CumulativeCreditUsage`

      Cumulative credit usage for this team.

  - `UnteamedUsage CumulativeCreditUsage`

    Usage by members not assigned to any team.

  - `UserUsage []UserCreditBudgetUsage`

    Per-user month-to-date usage for every user with usage in the period.
    The budget fields on each entry are populated only when a monthly budget
    applies to that user. This list is not paginated or capped; for large
    organizations prefer ListEnterpriseUserCreditUsage.

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

    - `CreditBudget string`

    - `DisplayName string`

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

    - `MonthToDateUsage CumulativeCreditUsage`

      CumulativeCreditUsage contains cumulative credit consumption totals.

    - `NoCap bool`

    - `OverBudget bool`

    - `UsageByModel []EnterpriseAIUsageByModel`

      Month-to-date 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`

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

func main() {
  client := gitpod.NewClient(
    option.WithBearerToken("My Bearer Token"),
  )
  response, err := client.Billing.GetCumulativeCreditUsage(context.TODO(), gitpod.BillingGetCumulativeCreditUsageParams{
    OrganizationID: gitpod.F("b0e12f6c-4c67-429d-a4a6-d9838b5da047"),
    AsOf: gitpod.F(time.Now()),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.OrgUsage)
}
```

#### Response

```json
{
  "orgUsage": {
    "totalCredits": 0,
    "usageByType": [
      {
        "credits": 0,
        "usageType": "USAGE_TYPE_UNSPECIFIED"
      }
    ]
  },
  "periodStart": "2019-12-27T18:11:19.117Z",
  "teamUsage": [
    {
      "creditBudget": "creditBudget",
      "displayName": "displayName",
      "teamId": "teamId",
      "usage": {
        "totalCredits": 0,
        "usageByType": [
          {
            "credits": 0,
            "usageType": "USAGE_TYPE_UNSPECIFIED"
          }
        ]
      }
    }
  ],
  "unteamedUsage": {
    "totalCredits": 0,
    "usageByType": [
      {
        "credits": 0,
        "usageType": "USAGE_TYPE_UNSPECIFIED"
      }
    ]
  },
  "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
    }
  ]
}
```