Skip to content
Ona API Reference
Ona Docs
API Reference
Billing

GetCreditUsageReport

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.

    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.

Body ParametersJSONExpand Collapse
dateRange: DateRange { endTime, startTime }

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.

endTime: string

End time of the date range (exclusive).

formatdate-time
startTime: string

Start time of the date range (inclusive).

formatdate-time
organizationId: string
formatuuid
filter: optional CreditUsageReportFilter { subject }

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.

subject: optional Subject { id, principal }

Restrict the per-user breakdown to a single subject. The subject must be PRINCIPAL_USER or PRINCIPAL_SERVICE_ACCOUNT and belong to the request’s organization. When unset, the report returns the default top-N users + “Others” breakdown.

When this field is set:

  • daily_usage[*].user_usage contains rows only for the requested subject; no “Others” aggregation bucket is produced.
  • daily_usage[*].org_usage, team_usage, environment_usage, and conversation_usage are omitted (empty). Callers that need those sections should issue an unfiltered call.
  • period_start and updated_at remain populated.
id: optional string

id is the UUID of the subject

formatuuid
principal: optional Principal

Principal is the principal of the subject

One of the following:
"PRINCIPAL_UNSPECIFIED"
"PRINCIPAL_ACCOUNT"
"PRINCIPAL_USER"
"PRINCIPAL_RUNNER"
"PRINCIPAL_ENVIRONMENT"
"PRINCIPAL_SERVICE_ACCOUNT"
"PRINCIPAL_RUNNER_MANAGER"
timezone: optional string

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

ReturnsExpand Collapse
dailyUsage: optional array of DailyCreditUsage { conversationUsage, date, environmentUsage, 4 more }

One entry per day in the requested date range.

conversationUsage: optional array of AgentExecutionCreditUsage { agentExecutionId, displayName, usage }

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

agentExecutionId: optional string

Empty when representing the “Others” aggregation bucket.

displayName: optional string
usage: optional array of CreditsByType { credits, usageType }
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"
date: optional string

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

formatdate-time
environmentUsage: optional array of EnvironmentCreditUsage { displayName, environmentId, usage }

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

displayName: optional string
environmentId: optional string

Empty when representing the “Others” aggregation bucket.

usage: optional array of CreditsByType { credits, usageType }
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"
orgUsage: optional array of CreditsByType { credits, usageType }

Org-wide usage broken down by 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"
teamUsage: optional array of TeamCreditUsage { displayName, teamId, usage }

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

displayName: optional string
teamId: optional string

Empty when representing the “Others” aggregation bucket.

usage: optional array of CreditsByType { credits, usageType }
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"
usageByModel: optional array of EnterpriseAIUsageByModel { model, unpricedUsage, unpricedUsageByTokenType, 2 more }

Org-wide 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
userUsage: optional array of UserCreditUsage { displayName, usage, usageByModel, userId }

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

displayName: optional string
usage: optional array of CreditsByType { credits, usageType }
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"
usageByModel: optional array of EnterpriseAIUsageByModel { model, unpricedUsage, unpricedUsageByTokenType, 2 more }

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

Empty when representing the “Others” aggregation bucket.

periodStart: optional string

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

formatdate-time
updatedAt: optional string

When the report data was last computed.

formatdate-time

GetCreditUsageReport

curl https://app.gitpod.io/api/gitpod.v1.BillingService/GetCreditUsageReport \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $GITPOD_API_KEY" \
    -d '{
          "dateRange": {
            "endTime": "2024-01-31T00:00:00Z",
            "startTime": "2024-01-01T00:00:00Z"
          },
          "organizationId": "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
        }'
{
  "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"
}
Returns Examples
{
  "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"
}