AI cost usage API

Available on the Enterprise plan. Contact sales to learn more.

The AI cost usage API exposes the BYOK (bring-your-own-key) spend data behind Settings → Cost & Budgets: organization totals, per-team and per-user attribution with budgets, and a daily time series. Use it to export AI spend to finance tools, find your top spenders, or track budget utilization. All four endpoints report BYOK token spend only. Usage from Ona Intelligence (Ona-managed models) is not included, and the credits field is never populated. For budget concepts, see User budgets.

Ona Intelligence or BYOK? Choose the right API

Ona meters AI usage one of two ways, depending on how your organization is set up. The two models have separate APIs:

Your setup	How usage is metered	Use
BYOK (your own provider keys)	Spend in your billing currency, via BYOK rate cards	This API
Ona Intelligence (Ona-managed models)	Credits (OCUs) consumed as you use environments and AI	Ona Intelligence usage API

Not sure which applies to you? Open Settings → Cost & Budgets: if usage is shown as spend in a currency (USD, EUR, or GBP), you are on BYOK (use this API); if it is shown in credits, you are using Ona Intelligence (use the Ona Intelligence usage API). The APIs also tell you directly: these cost endpoints return empty usage for organizations on Ona Intelligence, and the Ona Intelligence usage API returns FAILED_PRECONDITION with enterprise credit usage is not enabled for BYOK-only organizations.

Authentication

All endpoints accept a Bearer token: a personal access token (acts as you) or a service account token (owned by the organization, recommended for ongoing automation).

export GITPOD_API_KEY="your-token"

Organization admins and members with the Billing Viewer role can read all usage. Other members can read their own usage by setting filter.subject to themselves on the per-user endpoints.

Request format

Every endpoint is a POST with a JSON body:

POST https://app.gitpod.io/api/gitpod.v1.BillingService/<Method>

Parameter	Required	Description
`organizationId`	Yes	Your organization ID.
`dateRange`	Yes	`startTime` and `endTime` as RFC-3339 timestamps. Both dates are inclusive and the range must not exceed 31 days. Time-of-day is ignored; dates are truncated to midnight in the request timezone.
`timezone`	No	IANA timezone name used to bucket usage (for example `Europe/London`). Defaults to `UTC`.
`pagination`	List endpoints	`pageSize` and `token` for paging through results.

Responses follow three conventions:

Costs are reported as costMicrounits: millionths of the billing currency unit, so "84500000" with BILLING_CURRENCY_USD is $84.50. Currencies are BILLING_CURRENCY_USD, BILLING_CURRENCY_EUR, or BILLING_CURRENCY_GBP.
64-bit integer fields (costs, token counts, limits) are returned as JSON strings, per protobuf JSON encoding. Parse them as integers.
calculatedAt is the time through which usage has been calculated. Usage after that timestamp may still be processing, and fields with zero values are omitted from responses.

Organization usage summary

Returns organization-wide spend and token counts for the date range, the monthly budget when one applies, and a per-model breakdown. Usage that no configured BYOK rate matched is reported separately as unpricedUsage. Endpoint: POST https://app.gitpod.io/api/gitpod.v1.BillingService/GetEnterpriseAIUsageSummary Request:

curl https://app.gitpod.io/api/gitpod.v1.BillingService/GetEnterpriseAIUsageSummary \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{
       "organizationId": "<your-org-id>",
       "dateRange": {"startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-30T00:00:00Z"}
     }'

Response:

{
  "calculatedAt": "2026-07-09T11:58:02Z",
  "usage": {
    "costMicrounits": "84500000",
    "currency": "BILLING_CURRENCY_USD",
    "tokens": {
      "inputTokens": "48200000",
      "outputTokens": "6100000",
      "cacheTokens": "310400000",
      "totalTokens": "364700000"
    }
  },
  "budget": {
    "source": "ENTERPRISE_AI_USAGE_BUDGET_SOURCE_ORGANIZATION",
    "monthlyCostLimitMicrounits": "250000000",
    "currency": "BILLING_CURRENCY_USD",
    "monthToDateUsage": {
      "costMicrounits": "84500000",
      "currency": "BILLING_CURRENCY_USD"
    },
    "utilizationPercent": 33.8
  },
  "usageByModel": [
    {
      "model": "claude-opus-4-8",
      "usage": {
        "costMicrounits": "61200000",
        "currency": "BILLING_CURRENCY_USD",
        "tokens": { "inputTokens": "31500000", "outputTokens": "4400000", "cacheTokens": "228000000", "totalTokens": "263900000" }
      },
      "usageByTokenType": [
        { "tokenType": "BYOK_RATE_CARD_TOKEN_TYPE_INPUT", "usage": { "costMicrounits": "18900000", "currency": "BILLING_CURRENCY_USD" } },
        { "tokenType": "BYOK_RATE_CARD_TOKEN_TYPE_OUTPUT", "usage": { "costMicrounits": "26400000", "currency": "BILLING_CURRENCY_USD" } },
        { "tokenType": "BYOK_RATE_CARD_TOKEN_TYPE_CACHE_READ", "usage": { "costMicrounits": "15900000", "currency": "BILLING_CURRENCY_USD" } }
      ]
    }
  ]
}

budget is unset when no monthly budget applies to the organization. Token types are BYOK_RATE_CARD_TOKEN_TYPE_INPUT, BYOK_RATE_CARD_TOKEN_TYPE_OUTPUT, BYOK_RATE_CARD_TOKEN_TYPE_CACHE_READ, and BYOK_RATE_CARD_TOKEN_TYPE_CACHE_WRITE.

Per-team usage

Returns spend per team, with each team’s monthly budget when one applies. Filter to specific teams with filter.teamIds (up to 100). Endpoint: POST https://app.gitpod.io/api/gitpod.v1.BillingService/ListEnterpriseAITeamUsage Request:

curl https://app.gitpod.io/api/gitpod.v1.BillingService/ListEnterpriseAITeamUsage \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{
       "organizationId": "<your-org-id>",
       "dateRange": {"startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-30T00:00:00Z"},
       "pagination": {"pageSize": 50}
     }'

Response:

{
  "pagination": {},
  "calculatedAt": "2026-07-09T11:58:02Z",
  "teamUsage": [
    {
      "teamId": "d2c94c27-3b76-4a42-b88c-95a85e392c68",
      "displayName": "Platform",
      "usage": {
        "costMicrounits": "31800000",
        "currency": "BILLING_CURRENCY_USD",
        "tokens": { "inputTokens": "18400000", "outputTokens": "2300000", "cacheTokens": "119000000", "totalTokens": "139700000" }
      },
      "budget": {
        "source": "ENTERPRISE_AI_USAGE_BUDGET_SOURCE_TEAM",
        "monthlyCostLimitMicrounits": "50000000",
        "currency": "BILLING_CURRENCY_USD",
        "utilizationPercent": 63.6
      }
    }
  ]
}

Per-user usage

Returns spend for each user and service account with attributed usage, including each subject’s effective monthly budget. Usage not attributed to a user or service account is excluded, so the sum across subjects can be less than the organization totals. Budget fields (monthToDateUsage, utilizationPercent, overBudget) are computed from usage inside the requested date range measured against the monthly limit. Send a range that starts on the first day of the month for true month-to-date figures. Endpoint: POST https://app.gitpod.io/api/gitpod.v1.BillingService/ListEnterpriseAIUserUsage Request (top spenders first):

curl https://app.gitpod.io/api/gitpod.v1.BillingService/ListEnterpriseAIUserUsage \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{
       "organizationId": "<your-org-id>",
       "dateRange": {"startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-30T00:00:00Z"},
       "sort": {"field": "SORT_FIELD_USAGE", "order": "SORT_ORDER_DESC"},
       "pagination": {"pageSize": 50}
     }'

Response:

{
  "pagination": {},
  "totalCount": 24,
  "calculatedAt": "2026-07-09T11:58:02Z",
  "userUsage": [
    {
      "userId": "d2c94c27-3b76-4a42-b88c-95a85e392c68",
      "displayName": "Ada Lovelace",
      "monthToDateUsage": {
        "costMicrounits": "9400000",
        "currency": "BILLING_CURRENCY_USD",
        "tokens": { "inputTokens": "5200000", "outputTokens": "700000", "cacheTokens": "34100000", "totalTokens": "40000000" }
      },
      "monthlyCostLimitMicrounits": "10000000",
      "currency": "BILLING_CURRENCY_USD",
      "budgetSource": "ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_ORGANIZATION",
      "utilizationPercent": 94,
      "overBudget": false,
      "isServiceAccount": false
    }
  ]
}

Sort fields: SORT_FIELD_USAGE (default, spend), SORT_FIELD_DISPLAY_NAME, SORT_FIELD_BUDGET, SORT_FIELD_BUDGET_USED. Subjects without a budget sort last on the budget fields. noCap is true for subjects explicitly exempted from budget limits. To restrict the list to one user or service account:

curl https://app.gitpod.io/api/gitpod.v1.BillingService/ListEnterpriseAIUserUsage \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{
       "organizationId": "<your-org-id>",
       "dateRange": {"startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-30T00:00:00Z"},
       "filter": {"subject": {"id": "<user-id>", "principal": "PRINCIPAL_USER"}}
     }'

Daily time series

Returns one entry per day with spend totals and per-user, per-team, and per-model breakdowns. Per-user entries cover the top spenders, with the rest grouped into an “Others” bucket (empty userId). When filter.subject is set, the response contains only that subject’s usage: daily totals and the team breakdown are omitted, and the model breakdown covers the subject only. Endpoint: POST https://app.gitpod.io/api/gitpod.v1.BillingService/GetEnterpriseAIUsageTimeSeries Request:

curl https://app.gitpod.io/api/gitpod.v1.BillingService/GetEnterpriseAIUsageTimeSeries \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{
       "organizationId": "<your-org-id>",
       "dateRange": {"startTime": "2026-06-01T00:00:00Z", "endTime": "2026-06-07T00:00:00Z"},
       "timezone": "Europe/London"
     }'

Response:

{
  "calculatedAt": "2026-07-09T11:58:02Z",
  "dailyUsage": [
    {
      "date": "2026-06-01T00:00:00Z",
      "usage": {
        "costMicrounits": "2900000",
        "currency": "BILLING_CURRENCY_USD",
        "tokens": { "inputTokens": "1600000", "outputTokens": "210000", "cacheTokens": "10400000", "totalTokens": "12210000" }
      },
      "userUsage": [
        { "userId": "d2c94c27-3b76-4a42-b88c-95a85e392c68", "displayName": "Ada Lovelace", "usage": { "costMicrounits": "1200000", "currency": "BILLING_CURRENCY_USD" } },
        { "userId": "", "displayName": "Others", "usage": { "costMicrounits": "1700000", "currency": "BILLING_CURRENCY_USD" } }
      ],
      "teamUsage": [
        { "teamId": "b0e12f6c-4c67-429d-a4a6-d9838b5da047", "displayName": "Platform", "usage": { "costMicrounits": "1100000", "currency": "BILLING_CURRENCY_USD" } }
      ],
      "usageByModel": [
        { "model": "claude-opus-4-8", "usage": { "costMicrounits": "2100000", "currency": "BILLING_CURRENCY_USD" } }
      ]
    }
  ]
}

Get Started

Using Ona

Configuration

Administration & Security

Infrastructure

Billing

Learn

Reference

Support

Releases

AI cost usage API

Ona Intelligence or BYOK? Choose the right API

Authentication

Request format

Organization usage summary

Per-team usage

Per-user usage

Daily time series

​Ona Intelligence or BYOK? Choose the right API

​Authentication

​Request format

​Organization usage summary

​Per-team usage

​Per-user usage

​Daily time series

Ona Intelligence or BYOK? Choose the right API

Authentication

Request format

Organization usage summary

Per-team usage

Per-user usage

Daily time series