Ona Intelligence usage API

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

The Ona Intelligence usage API exposes the credit consumption data behind Settings → Cost & Budgets: daily usage broken down by type and by user, team, environment, and conversation; cumulative period totals with team allocations and per-user budgets; and a CSV export. Use it to export usage to finance tools, attribute spend across teams, or track budget utilization.

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
Ona Intelligence (Ona-managed models)	Credits (OCUs) consumed as you use environments and AI	This API
BYOK (your own provider keys)	Spend in your billing currency, via BYOK rate cards	AI cost usage API

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

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 on the report endpoint by setting filter.subject to their own user identity (this self-access path is for user tokens, not service accounts).

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`	Report, export	`startTime` and `endTime` as RFC-3339 timestamps. Both dates are inclusive; time-of-day is ignored. The report is capped at 31 days; the export may cover up to a year.
`asOf`	Cumulative, list	Point in time to compute month-to-date usage up to. Defaults to now.
`timezone`	No	IANA timezone name (for example `Europe/London`) used to bucket daily usage. Defaults to `UTC`.
`pagination`	List	`pageSize` and `token` for paging.

Response conventions:

Credits are floating-point values (for example 12.5). Budgets (creditBudget) are whole credits.
usageType is USAGE_TYPE_ENVIRONMENT (environment runtime) or USAGE_TYPE_AGENTIC (agent activity).
Token counts are returned as JSON strings, per protobuf JSON encoding.
Fields at their default value are omitted. creditBudget, utilizationPercent, and overBudget appear on a user only when a budget applies, overBudget and isServiceAccount only when true, and an unset budget or zero usage leaves the field out entirely.
periodStart marks the start of the billing period; usage before it is excluded.

Daily usage report

Returns one entry per day: org-wide credits by usage type, plus per-user, per-team, per-environment, and per-conversation breakdowns (top consumers with the rest grouped into an “Others” bucket), and a per-model breakdown of agent usage. Endpoint: POST https://app.gitpod.io/api/gitpod.v1.BillingService/GetCreditUsageReport Request:

curl https://app.gitpod.io/api/gitpod.v1.BillingService/GetCreditUsageReport \
     -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:

{
  "updatedAt": "2026-07-09T12:00:00Z",
  "periodStart": "2026-01-01T00:00:00Z",
  "dailyUsage": [
    {
      "date": "2026-06-01T00:00:00Z",
      "orgUsage": [
        { "usageType": "USAGE_TYPE_ENVIRONMENT", "credits": 41.5 },
        { "usageType": "USAGE_TYPE_AGENTIC", "credits": 918.25 }
      ],
      "userUsage": [
        { "userId": "d2c94c27-3b76-4a42-b88c-95a85e392c68", "displayName": "Ada Lovelace", "usage": [{ "usageType": "USAGE_TYPE_AGENTIC", "credits": 930.49 }] },
        { "userId": "", "displayName": "Others", "usage": [{ "usageType": "USAGE_TYPE_ENVIRONMENT", "credits": 33.0 }] }
      ],
      "teamUsage": [
        { "teamId": "b0e12f6c-4c67-429d-a4a6-d9838b5da047", "displayName": "Platform", "usage": [{ "usageType": "USAGE_TYPE_AGENTIC", "credits": 622.31 }] }
      ],
      "environmentUsage": [
        { "environmentId": "0191e4b2-6b3c-7973-a78b-68dc4a6da6b2", "displayName": "my-service", "usage": [{ "usageType": "USAGE_TYPE_ENVIRONMENT", "credits": 22.4 }] }
      ],
      "conversationUsage": [
        { "agentExecutionId": "019ee14b-2596-771d-82d2-ef9d3d16465d", "displayName": "Add pagination to the users table", "usage": [{ "usageType": "USAGE_TYPE_AGENTIC", "credits": 231.87 }] }
      ],
      "usageByModel": [
        {
          "model": "claude-opus-4-8",
          "usage": {
            "credits": 930.49,
            "tokens": { "inputTokens": "166562", "outputTokens": "898901", "cacheTokens": "154015590", "totalTokens": "155081053" }
          },
          "usageByTokenType": [
            { "tokenType": "BYOK_RATE_CARD_TOKEN_TYPE_CACHE_READ", "usage": { "credits": 892.86, "tokens": { "cacheTokens": "148810014", "totalTokens": "148810014" } } },
            { "tokenType": "BYOK_RATE_CARD_TOKEN_TYPE_OUTPUT", "usage": { "credits": 5.39, "tokens": { "outputTokens": "898901", "totalTokens": "898901" } } }
          ]
        }
      ]
    }
  ]
}

An empty userId (or teamId, environmentId, agentExecutionId) marks the “Others” bucket. Each userUsage entry also carries a usageByModel breakdown with the same shape as the day-level one shown here; teamUsage, environmentUsage, and conversationUsage do not. Token types (BYOK_RATE_CARD_TOKEN_TYPE_INPUT, _OUTPUT, _CACHE_READ, _CACHE_WRITE) apply to both Ona Intelligence and BYOK usage. To restrict the report to one subject, set filter.subject:

curl https://app.gitpod.io/api/gitpod.v1.BillingService/GetCreditUsageReport \
     -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"}}
     }'

When filter.subject is set, each day’s userUsage contains only that subject (no “Others” bucket), and the org, team, environment, and conversation breakdowns are omitted.

Cumulative period usage

Returns period-to-date totals for the organization, each team (with its credit allocation), members not on any team, and per-user month-to-date usage with budgets. Endpoint: POST https://app.gitpod.io/api/gitpod.v1.BillingService/GetCumulativeCreditUsage Request:

curl https://app.gitpod.io/api/gitpod.v1.BillingService/GetCumulativeCreditUsage \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{"organizationId": "<your-org-id>"}'

Response:

{
  "periodStart": "2026-01-01T00:00:00Z",
  "orgUsage": {
    "totalCredits": 1840.75,
    "usageByType": [
      { "usageType": "USAGE_TYPE_ENVIRONMENT", "credits": 1290.5 },
      { "usageType": "USAGE_TYPE_AGENTIC", "credits": 550.25 }
    ]
  },
  "teamUsage": [
    {
      "teamId": "b0e12f6c-4c67-429d-a4a6-d9838b5da047",
      "displayName": "Platform",
      "usage": { "totalCredits": 620.0, "usageByType": [{ "usageType": "USAGE_TYPE_AGENTIC", "credits": 240.0 }] },
      "creditBudget": "1000"
    }
  ],
  "unteamedUsage": { "totalCredits": 90.0 },
  "userUsage": [
    {
      "userId": "d2c94c27-3b76-4a42-b88c-95a85e392c68",
      "displayName": "Ada Lovelace",
      "monthToDateUsage": {
        "totalCredits": 120.5,
        "usageByType": [{ "usageType": "USAGE_TYPE_AGENTIC", "credits": 120.5 }]
      },
      "creditBudget": "150",
      "budgetSource": "ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_ORGANIZATION",
      "utilizationPercent": 80.3,
      "usageByModel": [
        { "model": "claude-opus-4-8", "usage": { "credits": 120.5, "tokens": { "inputTokens": "103422", "outputTokens": "63100", "cacheTokens": "35707859", "totalTokens": "35874381" } } }
      ]
    }
  ]
}

teamUsage returns all teams (no top-N limit). The userUsage list is not paginated or capped; for large organizations prefer the paginated list endpoint below. Each user carries a usageByModel breakdown; budget fields appear only when a monthly budget applies (overBudget only when the user is over it), and noCap is true for users exempted from limits.

Per-user usage list

Returns per-user month-to-date usage with budgets, paginated. Ordered by total credits descending by default so the highest spenders appear first. Endpoint: POST https://app.gitpod.io/api/gitpod.v1.BillingService/ListEnterpriseUserCreditUsage Request:

curl https://app.gitpod.io/api/gitpod.v1.BillingService/ListEnterpriseUserCreditUsage \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer $GITPOD_API_KEY" \
     -d '{
       "organizationId": "<your-org-id>",
       "sort": {"field": "SORT_FIELD_USAGE", "order": "SORT_ORDER_DESC"},
       "pagination": {"pageSize": 50}
     }'

Response:

{
  "totalCount": 24,
  "pagination": { "nextToken": "d2c94c27-3b76-4a42-b88c-95a85e392c68" },
  "userUsage": [
    {
      "userId": "d2c94c27-3b76-4a42-b88c-95a85e392c68",
      "displayName": "Ada Lovelace",
      "monthToDateUsage": {
        "totalCredits": 1320.37,
        "usageByType": [
          { "usageType": "USAGE_TYPE_ENVIRONMENT", "credits": 177.78 },
          { "usageType": "USAGE_TYPE_AGENTIC", "credits": 1142.59 }
        ]
      },
      "creditBudget": "500",
      "budgetSource": "ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_USER",
      "utilizationPercent": 264.07,
      "overBudget": true,
      "usageByModel": [
        { "model": "claude-opus-4-8", "usage": { "credits": 1142.59, "tokens": { "inputTokens": "166562", "outputTokens": "898901", "cacheTokens": "154015590", "totalTokens": "155081053" } } }
      ]
    }
  ]
}

The page token (nextToken) is the last user’s ID. budgetSource is ENTERPRISE_AI_USER_BUDGET_POLICY_SOURCE_ORGANIZATION, _USER, or _NONE. Sort fields: SORT_FIELD_USAGE (default, total credits), SORT_FIELD_DISPLAY_NAME, SORT_FIELD_BUDGET, SORT_FIELD_BUDGET_USED. The default usage ordering paginates over any number of users. The other three sorts compute the order in memory and are limited to organizations with at most 10,000 users; beyond that, use SORT_FIELD_USAGE. Because month-to-date figures are recomputed per request, hold asOf stable across a paginated walk to keep page tokens valid.

CSV export

Returns a short-lived, signed download URL for a gzip-compressed CSV. The download must be made by the same principal that requested it, carrying its own bearer token. Endpoint: POST https://app.gitpod.io/api/gitpod.v1.BillingService/GetCreditUsageExport Request:

curl https://app.gitpod.io/api/gitpod.v1.BillingService/GetCreditUsageExport \
     -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"},
       "groupBy": "CREDIT_USAGE_EXPORT_GROUP_BY_DAILY_SUMMARY"
     }'

Response:

{
  "downloadUrl": "https://app.gitpod.io/billing/credit-usage-export/<signed-token>"
}

Then download within five minutes, sending your token:

curl -L -H "Authorization: Bearer $GITPOD_API_KEY" "$DOWNLOAD_URL" | gunzip > credit-usage.csv

groupBy is CREDIT_USAGE_EXPORT_GROUP_BY_DAILY_SUMMARY (per-user daily summary, the default) or CREDIT_USAGE_EXPORT_GROUP_BY_RESOURCE (per-environment and per-conversation breakdown).

​Ona Intelligence or BYOK? Choose the right API

​Authentication

​Request format

​Daily usage report

​Cumulative period usage

​Per-user usage list

​CSV export

Ona Intelligence or BYOK? Choose the right API

Authentication

Request format

Daily usage report

Cumulative period usage

Per-user usage list

CSV export