Skip to content
Ona API Reference
Ona Docs
API Reference
Billing

GetCumulativeCreditUsage

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.

Body ParametersJSONExpand Collapse
organizationId: string

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

formatuuid
asOf: optional string

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

formatdate-time
ReturnsExpand Collapse
orgUsage: optional CumulativeCreditUsage { totalCredits, usageByType }

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

totalCredits: optional number

Total credits consumed.

formatdouble
usageByType: optional array of CreditsByType { credits, usageType }

Credits consumed broken down by usage type.

credits: optional number
formatdouble
usageType: optional UsageType

UsageType identifies the category of usage.

One of the following:
"USAGE_TYPE_UNSPECIFIED"
"USAGE_TYPE_ENVIRONMENT"
"USAGE_TYPE_AGENTIC"
periodStart: optional string

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

formatdate-time
teamUsage: optional array of TeamCumulativeCreditUsage { creditBudget, displayName, teamId, usage }

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

creditBudget: optional string

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

displayName: optional string
teamId: optional string
usage: optional CumulativeCreditUsage { totalCredits, usageByType }

Cumulative credit usage for this team.

totalCredits: optional number

Total credits consumed.

formatdouble
usageByType: optional array of CreditsByType { credits, usageType }

Credits consumed broken down by usage type.

credits: optional number
formatdouble
usageType: optional UsageType

UsageType identifies the category of usage.

One of the following:
"USAGE_TYPE_UNSPECIFIED"
"USAGE_TYPE_ENVIRONMENT"
"USAGE_TYPE_AGENTIC"
unteamedUsage: optional CumulativeCreditUsage { totalCredits, usageByType }

Usage by members not assigned to any team.

totalCredits: optional number

Total credits consumed.

formatdouble
usageByType: optional array of CreditsByType { credits, usageType }

Credits consumed broken down by usage type.

credits: optional number
formatdouble
usageType: optional UsageType

UsageType identifies the category of usage.

One of the following:
"USAGE_TYPE_UNSPECIFIED"
"USAGE_TYPE_ENVIRONMENT"
"USAGE_TYPE_AGENTIC"
userUsage: optional array of UserCreditBudgetUsage { budgetSource, creditBudget, displayName, 7 more }

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: optional EnterpriseAIUserBudgetPolicySource
One of the following:
"ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_UNSPECIFIED"
"ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_NONE"
"ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_ORGANIZATION"
"ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_USER"
creditBudget: optional string
displayName: optional string
isServiceAccount: optional boolean

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: optional CumulativeCreditUsage { totalCredits, usageByType }

CumulativeCreditUsage contains cumulative credit consumption totals.

totalCredits: optional number

Total credits consumed.

formatdouble
usageByType: optional array of CreditsByType { credits, usageType }

Credits consumed broken down by usage type.

credits: optional number
formatdouble
usageType: optional UsageType

UsageType identifies the category of usage.

One of the following:
"USAGE_TYPE_UNSPECIFIED"
"USAGE_TYPE_ENVIRONMENT"
"USAGE_TYPE_AGENTIC"
noCap: optional boolean
overBudget: optional boolean
usageByModel: optional array of EnterpriseAIUsageByModel { model, unpricedUsage, unpricedUsageByTokenType, 2 more }

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

model: optional string
unpricedUsage: optional EnterpriseAIUsage { costMicrounits, credits, currency, tokens }

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

costMicrounits: optional string
credits: optional number
formatdouble
currency: optional BillingCurrency
One of the following:
"BILLING_CURRENCY_UNSPECIFIED"
"BILLING_CURRENCY_USD"
"BILLING_CURRENCY_EUR"
"BILLING_CURRENCY_GBP"
tokens: optional EnterpriseAITokenUsage { cacheTokens, inputTokens, outputTokens, totalTokens }
cacheTokens: optional string
inputTokens: optional string
outputTokens: optional string
totalTokens: optional string
unpricedUsageByTokenType: optional array of EnterpriseAIUsageByTokenType { tokenType, usage }
tokenType: optional ByokRateCardTokenType
One of the following:
"BYOK_RATE_CARD_TOKEN_TYPE_UNSPECIFIED"
"BYOK_RATE_CARD_TOKEN_TYPE_INPUT"
"BYOK_RATE_CARD_TOKEN_TYPE_OUTPUT"
"BYOK_RATE_CARD_TOKEN_TYPE_CACHE_READ"
"BYOK_RATE_CARD_TOKEN_TYPE_CACHE_WRITE"
usage: optional EnterpriseAIUsage { costMicrounits, credits, currency, tokens }
costMicrounits: optional string
credits: optional number
formatdouble
currency: optional BillingCurrency
One of the following:
"BILLING_CURRENCY_UNSPECIFIED"
"BILLING_CURRENCY_USD"
"BILLING_CURRENCY_EUR"
"BILLING_CURRENCY_GBP"
tokens: optional EnterpriseAITokenUsage { cacheTokens, inputTokens, outputTokens, totalTokens }
cacheTokens: optional string
inputTokens: optional string
outputTokens: optional string
totalTokens: optional string
usage: optional EnterpriseAIUsage { costMicrounits, credits, currency, tokens }
costMicrounits: optional string
credits: optional number
formatdouble
currency: optional BillingCurrency
One of the following:
"BILLING_CURRENCY_UNSPECIFIED"
"BILLING_CURRENCY_USD"
"BILLING_CURRENCY_EUR"
"BILLING_CURRENCY_GBP"
tokens: optional EnterpriseAITokenUsage { cacheTokens, inputTokens, outputTokens, totalTokens }
cacheTokens: optional string
inputTokens: optional string
outputTokens: optional string
totalTokens: optional string
usageByTokenType: optional array of EnterpriseAIUsageByTokenType { tokenType, usage }
tokenType: optional ByokRateCardTokenType
One of the following:
"BYOK_RATE_CARD_TOKEN_TYPE_UNSPECIFIED"
"BYOK_RATE_CARD_TOKEN_TYPE_INPUT"
"BYOK_RATE_CARD_TOKEN_TYPE_OUTPUT"
"BYOK_RATE_CARD_TOKEN_TYPE_CACHE_READ"
"BYOK_RATE_CARD_TOKEN_TYPE_CACHE_WRITE"
usage: optional EnterpriseAIUsage { costMicrounits, credits, currency, tokens }
costMicrounits: optional string
credits: optional number
formatdouble
currency: optional BillingCurrency
One of the following:
"BILLING_CURRENCY_UNSPECIFIED"
"BILLING_CURRENCY_USD"
"BILLING_CURRENCY_EUR"
"BILLING_CURRENCY_GBP"
tokens: optional EnterpriseAITokenUsage { cacheTokens, inputTokens, outputTokens, totalTokens }
cacheTokens: optional string
inputTokens: optional string
outputTokens: optional string
totalTokens: optional string
userId: optional string
utilizationPercent: optional number
formatdouble

GetCumulativeCreditUsage

curl https://app.gitpod.io/api/gitpod.v1.BillingService/GetCumulativeCreditUsage \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{
          "organizationId": "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
        }'
{
  "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
    }
  ]
}