GitLab Credits dashboard

  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

The GitLab Credits dashboard displays information about your usage of GitLab Credits. Use the dashboard to monitor credit consumption, track trends, and identify usage patterns.

To help you manage credit consumption, GitLab emails the following information to Customers Portal users linked to the billing account:

  • Monthly credit usage summaries
  • Notifications when credit usage thresholds are at 50%, 80%, and 100%

You can access the dashboard in the Customers Portal and in GitLab. On GitLab Dedicated, the dashboard is available in the Customers Portal and to instance administrators. Group-level and personal credit usage views are available on GitLab.com only.

Usage data is not displayed in real time. Data is synchronized to the dashboards periodically, so usage data should appear within a few hours of actual consumption. This means your dashboard shows recent usage, but might not reflect actions taken in the last few hours.

In Customers Portal

The GitLab Credits dashboard in the Customers Portal provides the most detailed view of your usage and costs.

On the dashboard, used credits represent deductions from available credits. For overages (on-demand credits), used credits represent on-demand usage that will be paid later, if you have agreed to the usage billing terms.

The dashboard displays summary cards of key metrics:

  • Current month usage: Total GitLab Credits used in the current month (if you have a monthly commitment)
  • Included credits: Total credits included with your subscription (if you have a monthly commitment)
  • Committed credits: Credits from your monthly commitment pool (if applicable)
  • Monthly waivers: Remaining credits from waivers (if applicable)
  • On-demand usage: Credits consumed beyond your included and committed amounts. If you have enough waiver credits to offset all on-demand credits, the GitLab Credits Dashboard hides the On-Demand card and displays the Monthly Waiver card instead.
  • Usage control status: Whether individual users have been blocked from Agent Platform access due to reaching their per-user credit cap.

In GitLab

Some pre-release features, such as the Security Review Flow, are billable and subject to GitLab Credits charges.

The GitLab Credits dashboard in GitLab provides operational visibility into the usage of credits in your organization. Use the dashboard to understand which users, groups, or projects are driving usage, and make informed decisions about resource allocation.

The dashboard displays the following information:

  • Organization usage: Total credit usage (billed and non-billable), active users, daily credit average, and peak day usage across your GitLab instance or group
  • Total credit consumption: Daily billed and non-billable credit consumption over all products, displayed as a stacked bar chart
  • Usage by user: Number of credits used by each user
  • User drill-down view: Individual usage events for each user, with links to session details for each credit-based feature
  • Usage by product: Number of credits used and percentage of total credits for credit-based features

While GitLab Secrets Manager is in beta, GitLab does not bill for usage. Secrets Manager appears in the Credits dashboard but displays no usage data until the beta period ends.

Non-billable usage

Non-billable usage is credit consumption that GitLab does not bill. The Total credit consumption chart displays:

  • Billable: Number of billable credits used
  • Non-billable: Number of non-billable credits used, shown only when the selected period includes non-billable usage
  • Stacked bars: Daily credits used, with Billable usage and Non-billable usage reasons as separate series

The chart displays the following non-billable usage series:

Series Description
Non-billable usage (Promotional) Usage covered by a promotion.
Non-billable usage (Beta) Usage of a feature that is not billable yet.
Non-billable usage (Other) Usage that was not billed for any other reason.

The chart displays only the reasons for usage in the selected period. If non-billable usage data is temporarily unavailable, the chart displays billable usage only.

View the GitLab Credits dashboard

Prerequisites:

  • To view detailed usage information, you must be a billing account manager.
  1. Sign in to Customers Portal.
  2. On the subscription card, select GitLab Credits dashboard.
  3. Optional. To view a previous month, from the Usage period dropdown list, select a period you want to view.
  4. Optional. To sort the results by User or Total credits used, select the respective column.

Prerequisites:

  • You must have the Owner role for the group.
  1. In the top bar, select Search or go to and find your top-level group.
  2. Select Settings > GitLab Credits.
  3. Optional. To sort the results by User or Total credits used, select the respective column.

Prerequisites:

  • You must be an administrator.
  • Your instance must be able to synchronize your subscription data with GitLab.
  1. In the upper-right corner, select Admin.
  2. In the left sidebar, select GitLab Credits.
  3. Optional. To sort the results by User or Total credits used, select the respective column.

By default, individual user data is not displayed in the GitLab Credits dashboard. To display it, you must enable this setting for your group or instance.

Non-human subject usage

Credit consumption can be triggered by either a human user or a non-human subject (for example, an AI feature like the SAST False Positive Detection Flow).

To help you identify where credits are consumed, the Usage by user tab on the GitLab Credits dashboard displays an Automated flow badge next to the rows that represent non-human subjects. Rows without the badge represent human users.

The display of the Automated flow badge is controlled by the setting Display GitLab Credits user data, which is available for groups and instances.

Usage caps

You can set a monthly GitLab Credits cap at the subscription and user level to prevent unexpected overage charges. When credit consumption reaches the configured cap, access to credit-based features is automatically suspended until the next billing period begins, or until an administrator adjusts or disables the cap.

The following cap types are available:

Cap type Applies to Credit sources counted Managed through
Subscription cap All users on the subscription On-demand only Customers Portal
Flat user cap Individual users (default limit) All, for human subject usage User interface, GraphQL API
Per-user override A specific user’s total usage, including their included credits. Overrides the flat cap. A user can therefore consume up to whichever is larger: their included allocation, or their cap. All, for human subject usage User interface, GraphQL API

When on-demand usage in the current billing period reaches or exceeds the configured cap, all credit-based features are suspended for all users on that subscription or instance, and GitLab sends an email notification to billing account managers. For user-level caps, only the individual user who reached their cap is suspended.

Flat user caps and per-user override caps apply to usage beyond a user’s included allocation. While a user still has included credits, they can continue to consume their included credits even after their usage reaches the cap. The cap is enforced only after the user’s included credits are exhausted.

Users who have reached their cap are unable to access Agent Platform features until the cap is raised or the next billing period begins.

Usage counters reset automatically at the start of each billing period. Cap values persist across billing periods unless changed.

Caps are enforced using the most recent usage data available. Because data is not real time, limited additional GitLab Credits usage may occur before enforcement takes effect.

Caps do not stop users from consuming their included GitLab Credits. Enforcement begins per user, and only after that user’s included allocation is exhausted. Until then, the user retains full GitLab Duo Agent Platform access regardless of the cap value, including a cap of 0.

To stop all GitLab Credits consumption immediately, regardless of included balances, remove the GitLab Duo seat from the affected users, or turn off GitLab Duo for the namespace. To automate seat removal and reassignment, use the userAddOnAssignmentRemove and userAddOnAssignmentCreate GraphQL mutations.

How the cap value is applied then depends on the cap type:

  • A subscription-level cap applies to on-demand usage only. The cap is the amount of on-demand usage allowed across the subscription, in addition to every user’s included credits.
  • A per-user cap applies to a user’s total usage, including their included credits, for usage the user triggers directly. A user can therefore consume up to whichever is larger: their included allocation, or their cap.

Usage from GitLab Duo Agent Platform flows that run under a service account is billed to the namespace, not to the user, and does not count toward the user’s flat cap or per-user override. This usage can still appear in the user’s Total credits used, so their displayed usage can exceed their cap without the user being blocked. To limit this usage, set a subscription-level cap or remove the user’s GitLab Duo seat.

Examples

For a subscription-level cap, consider a subscription that has 10 users, each with 100 included GitLab Credits. The billing account manager sets the subscription-level on-demand cap to 0.

  • A user who has already used all 100 of their included credits is blocked from Agent Platform features immediately (on the next enforcement check), because any further usage would be on-demand.
  • A user who has only used 40 of their included credits can continue using Agent Platform features and consume their remaining 60 included credits. The 0 cap does not apply to them yet.

For a per-user cap, consider a user that has 24 included GitLab Credits.

  • With a per-user cap of 50, the user is blocked after 50 credits in total, 26 credits beyond their included allocation.
  • With a per-user cap of 10, the user is blocked after 24 credits, when their included allocation is exhausted.

Set a subscription-level usage cap

Prerequisites:

  • You must be a billing account manager.
  1. Sign in to Customers Portal.
  2. On the subscription card, select GitLab Credits dashboard.
  3. Select Spend controls.
  4. In the On-demand credit cap panel, turn on the Set on-demand credit cap toggle.
  5. Enter the maximum number of on-demand GitLab Credits allowed per billing period.
  6. Select Save Changes.

If the cap is set below the currently reported total on-demand usage for the current billing period, the cap is considered reached immediately on the next enforcement check.

To disable the cap, turn off the Set on-demand credit cap toggle. When disabled, no subscription-level on-demand GitLab Credits cap is enforced, and behavior falls back to existing billing behavior.

You can use the GraphQL API to view usage caps and set a flat user-level cap or a per-user override cap.

Manage credit caps

The availability of this feature is controlled by a feature flag. For more information, see the history.

To manage credit caps:

Prerequisites:

  • The Owner role for the group.
  1. In the top bar, select Search or go to and find your top-level group.
  2. Select Settings > GitLab Credits.
  3. Select Credit caps.

Prerequisites:

  • Administrator access.
  1. In the upper-right corner, select Admin.
  2. In the left sidebar, select GitLab Credits.
  3. Select Credit caps.

On the Credit caps page, you can set the following:

  • Flat user cap: A default credit cap for all users on the subscription.
  • Per-user cap overrides: A specific cap for individual users that overrides the flat user cap.

Set a flat user cap

To set a flat user cap that applies to all users by default:

  1. Enter the maximum number of GitLab Credits a user can consume per billing period.
  2. Turn on the toggle to enable enforcement.
  3. Select Save.

Set per-user cap overrides

You can add, update, and turn off cap overrides for individual users.

To add an override:

  1. Select Add override.
  2. Select one or more users.
  3. Set the cap value and turn the Enabled toggle on or off.
  4. Select Save.

To update an override:

  1. Under Per-user cap overrides, adjust the cap value for the user and turn the Enabled toggle on or off.
  2. Select Save.

To turn off an override:

  1. Under Per-user cap overrides, turn the Enabled toggle off for the user.
  2. Select Save.

Bulk update overrides

The availability of this feature is controlled by a feature flag. For more information, see the history.

Use bulk updates to add or change overrides for many users at once.

You can paste a CSV list of users, which merges into the existing list of overrides, adding new records or updating existing ones.

To bulk update per-user cap overrides:

  1. Under Per-user cap overrides, select Bulk update.
  2. In the modal, paste a CSV list.
  3. Select Save.

The input accepts three columns, separated by commas. You can add an optional header row on the first line. The header row must be username,cap,enabled, and is not case-sensitive. If any validation fails or a username is not found, the entire update is rejected and no changes are saved.

Column Type Accepted values
username String GitLab username without the @ prefix (for example, jsmith, not @jsmith)
cap Number Non-negative number. Use . as the decimal separator for fractional values (for example, 0, 500, 1000.5).
enabled Boolean true, True, TRUE, false, False, FALSE

Example:

username,cap,enabled
sidney.jones,500,true
zhang.wei,1000.5,True
alex.garcia,250,false

Example without a header row:

sidney.jones,500,true
zhang.wei,1000.5,True
alex.garcia,250,false

Usage control status

When per-user credit caps are enabled, the Usage by user tab on the GitLab Credits dashboard displays a Usage control status column. This column shows whether each user can access credit-based features or is blocked because they reached their credit cap.

The Usage control status column displays the status Blocked usage only when GitLab enforces the cap against the user. GitLab enforces the cap after the user’s included credits are exhausted. A user who has reached their cap but still has included credits has the status Regular usage, because they can continue to consume their included credits.

The column displays one of the following statuses:

Status Description
Regular usage The user has not reached their credit cap, or has reached their cap but still has included credits, and can use GitLab Duo Agent Platform features.
Blocked usage The user has exhausted their included credits and reached their per-user cap. The cap is either the flat user cap set for all users on the subscription, or a per-user override cap set specifically for them.

The dashboard does not display which type of cap blocked a user. To determine the cap type, use the GraphQL API.

The Usage control status column displays only per-user caps. The subscription-level on-demand cap applies to the entire subscription, not to individual users, and is not listed in this column.

The status reflects only the usage the user triggers directly. Rows with the Automated flow badge represent non-human subjects and never display Blocked usage, because per-user caps do not apply to them.

Unblock a user who reached their credit cap

You can restore access for a blocked user by using the per-user override GraphQL API.

To unblock a user, either:

  • Increase the cap: Set a higher per-user override cap so the user’s usage falls below the new limit.
  • Remove the cap: Delete the per-user override so the user is no longer subject to an individual cap.

After you update the cap, the user’s status changes to Regular usage and they can use credit-based features again.

View user credit usage details

To view a user’s individual usage events in a drill-down view:

  1. In the GitLab Credits dashboard, select the Usage by user tab.
  2. In the User column, select the user you want to view.
  3. To view session details, in the Action column, select the action you want to view.

Session links are available only for GitLab Duo Agent Platform usage events that are triggered in a project and have an associated session ID. Usage events triggered in a group, legacy events, and actions outside Agent Platform don’t have links.

Export usage data

You can export the credit usage data for a subscription in Customers Portal. The export runs in the background, and GitLab emails you a link to download the result. The download link expires after seven days.

The download is a ZIP file that contains two CSV files:

  • A daily summary file that lists the usage events and credits used on each day of the selected period.
  • A per-event file with one row for each billable event, including the product, flow type, session, user ID, namespace, project, credits used, and token counts.

Each export covers a period of up to 31 days.

Prerequisites:

  • You must be a billing account manager.
  1. Sign in to Customers Portal.
  2. On the subscription card, select GitLab Credits dashboard.
  3. From the Usage period dropdown list, select the period you want to export data for.
  4. Select Export usage data.

View your GitLab Credits usage

  • Offering: GitLab.com

You can track the GitLab Credits you consume in a top-level group in the Your GitLab Credits usage page. The dashboard reports only credit consumption. It does not show your remaining credits or a credit cap.

Your GitLab Credits usage displays:

  • Your usage for the current billing period.
  • A chart of your daily credit consumption for the selected date range and products.
  • Total usage: Total number of credits used in the selected date range and products.
  • Daily average: Average number of credits used in a day for the selected date range and products.
  • Peak day usage: The highest number of credits consumed in a single day for the selected date range and products.

Prerequisites:

  • You must be a member of a top-level group with a subscription that includes GitLab Credits.

To view your GitLab Credits usage:

  1. In the upper-right corner, select your avatar.
  2. Select Preferences.
  3. In the left sidebar, select GitLab Credits.
  4. If you are a member of multiple groups, from the Group dropdown list, select a top-level group.
  5. Optional. From the Date range dropdown list, select the date range you want to view your usage for. Default is the current month.
  6. Optional. From the Products dropdown list, select the products you want to include.