Skip to content
Ona API Reference
Ona Docs
API Reference
Billing

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:

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

  • Get cumulative usage as of a specific date:

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

Authorization

Requires billing:read_usage permission on the organization.

ParametersExpand Collapse
body BillingGetCumulativeCreditUsageParams
OrganizationID param.Field[string]

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

formatuuid
AsOf param.Field[Time]Optional

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

formatdate-time
ReturnsExpand Collapse
type BillingGetCumulativeCreditUsageResponse struct{…}
OrgUsage CumulativeCreditUsageOptional

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

TotalCredits float64Optional

Total credits consumed.

formatdouble
UsageByType []CreditsByTypeOptional

Credits consumed broken down by usage type.

Credits float64Optional
formatdouble
UsageType UsageTypeOptional

UsageType identifies the category of usage.

One of the following:
const UsageTypeUnspecified UsageType = "USAGE_TYPE_UNSPECIFIED"
const UsageTypeEnvironment UsageType = "USAGE_TYPE_ENVIRONMENT"
const UsageTypeAgentic UsageType = "USAGE_TYPE_AGENTIC"
PeriodStart TimeOptional

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

formatdate-time
TeamUsage []TeamCumulativeCreditUsageOptional

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

CreditBudget stringOptional

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

DisplayName stringOptional
TeamID stringOptional
Usage CumulativeCreditUsageOptional

Cumulative credit usage for this team.

TotalCredits float64Optional

Total credits consumed.

formatdouble
UsageByType []CreditsByTypeOptional

Credits consumed broken down by usage type.

Credits float64Optional
formatdouble
UsageType UsageTypeOptional

UsageType identifies the category of usage.

One of the following:
const UsageTypeUnspecified UsageType = "USAGE_TYPE_UNSPECIFIED"
const UsageTypeEnvironment UsageType = "USAGE_TYPE_ENVIRONMENT"
const UsageTypeAgentic UsageType = "USAGE_TYPE_AGENTIC"
UnteamedUsage CumulativeCreditUsageOptional

Usage by members not assigned to any team.

TotalCredits float64Optional

Total credits consumed.

formatdouble
UsageByType []CreditsByTypeOptional

Credits consumed broken down by usage type.

Credits float64Optional
formatdouble
UsageType UsageTypeOptional

UsageType identifies the category of usage.

One of the following:
const UsageTypeUnspecified UsageType = "USAGE_TYPE_UNSPECIFIED"
const UsageTypeEnvironment UsageType = "USAGE_TYPE_ENVIRONMENT"
const UsageTypeAgentic UsageType = "USAGE_TYPE_AGENTIC"
UserUsage []UserCreditBudgetUsageOptional

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.

One of the following:
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 stringOptional
DisplayName stringOptional
IsServiceAccount boolOptional

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 CumulativeCreditUsageOptional

CumulativeCreditUsage contains cumulative credit consumption totals.

TotalCredits float64Optional

Total credits consumed.

formatdouble
UsageByType []CreditsByTypeOptional

Credits consumed broken down by usage type.

Credits float64Optional
formatdouble
UsageType UsageTypeOptional

UsageType identifies the category of usage.

One of the following:
const UsageTypeUnspecified UsageType = "USAGE_TYPE_UNSPECIFIED"
const UsageTypeEnvironment UsageType = "USAGE_TYPE_ENVIRONMENT"
const UsageTypeAgentic UsageType = "USAGE_TYPE_AGENTIC"
NoCap boolOptional
OverBudget boolOptional
UsageByModel []EnterpriseAIUsageByModelOptional

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

Model stringOptional
UnpricedUsage EnterpriseAIUsageOptional

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

CostMicrounits stringOptional
Credits float64Optional
formatdouble
Currency BillingCurrencyOptional
One of the following:
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 EnterpriseAITokenUsageOptional
CacheTokens stringOptional
InputTokens stringOptional
OutputTokens stringOptional
TotalTokens stringOptional
UnpricedUsageByTokenType []EnterpriseAIUsageByTokenTypeOptional
TokenType ByokRateCardTokenTypeOptional
One of the following:
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 EnterpriseAIUsageOptional
CostMicrounits stringOptional
Credits float64Optional
formatdouble
Currency BillingCurrencyOptional
One of the following:
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 EnterpriseAITokenUsageOptional
CacheTokens stringOptional
InputTokens stringOptional
OutputTokens stringOptional
TotalTokens stringOptional
Usage EnterpriseAIUsageOptional
CostMicrounits stringOptional
Credits float64Optional
formatdouble
Currency BillingCurrencyOptional
One of the following:
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 EnterpriseAITokenUsageOptional
CacheTokens stringOptional
InputTokens stringOptional
OutputTokens stringOptional
TotalTokens stringOptional
UsageByTokenType []EnterpriseAIUsageByTokenTypeOptional
TokenType ByokRateCardTokenTypeOptional
One of the following:
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 EnterpriseAIUsageOptional
CostMicrounits stringOptional
Credits float64Optional
formatdouble
Currency BillingCurrencyOptional
One of the following:
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 EnterpriseAITokenUsageOptional
CacheTokens stringOptional
InputTokens stringOptional
OutputTokens stringOptional
TotalTokens stringOptional
UserID stringOptional
UtilizationPercent float64Optional
formatdouble

GetCumulativeCreditUsage

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)
}

{
  "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
    }
  ]
}
Returns Examples
{
  "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
    }
  ]
}