How to View GitLab Credits Usage Per Feature Using GraphQL

Description

This article explains how to query GitLab Credits usage broken down by individual feature or flow type for the current month using the subscriptionUsage GraphQL query. The query returns creditsUsed per requested flow type, giving you a direct programmatic view of per-feature consumption without navigating the GitLab Credits dashboard.

The query scope differs by offering:

GitLab.com: The query is scoped to a top-level namespace (group). You must supply the namespacePath argument. Instance-level queries are not available to customers on GitLab.com.
GitLab Dedicated and GitLab Self-Managed: The query can be scoped to either the entire instance (omit namespacePath) or a specific top-level namespace (supply namespacePath).

Impacted Offerings

GitLab.com
GitLab Dedicated
GitLab Self-Managed

Prerequisites

GitLab 18.5 or later (the subscriptionUsage GraphQL field was introduced in GitLab 18.5).
Access to the GitLab GraphQL Explorer or a GraphQL client with a personal access token that has the read_api scope.
The appropriate permissions for your offering:
- GitLab.com: Owner role on the top-level group (root namespace) you want to query.
- GitLab Dedicated: Owner role on the top-level group for a namespace-scoped query, or an instance administrator account for an instance-level query.
- GitLab Self-Managed: Owner role on the top-level group for a namespace-scoped query, or an instance administrator account for an instance-level query.

Solution

GitLab.com

On GitLab.com, the subscriptionUsage query is scoped to a top-level namespace. You must provide the namespacePath argument set to the path of your root group. Instance-level queries (omitting namespacePath) are not available to customers on GitLab.com.

Step 1: Open the GraphQL Explorer

Navigate to https://gitlab.com/-/graphql-explorer and sign in with an account that has the Owner role on the top-level group you want to query.

Step 2: Discover available flow types (optional)

If you are unsure which flow types are available, run the following discovery query first. Replace your-top-level-group with the path of your root group:

query getFlowTypes {
  subscriptionUsage(namespacePath: "your-top-level-group") {
    products {
      id
      title
      flowTypes {
        id
        title
      }
    }
  }
}

Use the id values returned by this query to build the per-feature query in the next step.

Step 3: Query GitLab Credits usage per feature

Run the following query to retrieve creditsUsed for each flow type in the current month for your top-level group. Replace your-top-level-group with the path of your root group. Each aliased field targets a single flow type so that the response contains one creditsUsed value per feature.

query getCreditsPerFlowType {
  # Duo Agent Platform
  ai_catalog_agent: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["ai_catalog_agent"]) { creditsUsed }
  analytics_agent: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["analytics_agent"]) { creditsUsed }
  chat: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["chat"]) { creditsUsed }
  code_review: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["code_review"]) { creditsUsed }
  code_suggestions: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["code_suggestions"]) { creditsUsed }
  convert_to_gl_ci: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["convert_to_gl_ci"]) { creditsUsed }
  dap_feature_legacy: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["dap_feature_legacy"]) { creditsUsed }
  developer: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["developer"]) { creditsUsed }
  duo_chat_classic: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["duo_chat_classic"]) { creditsUsed }
  duo_planner: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["duo_planner"]) { creditsUsed }
  fix_pipeline: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["fix_pipeline"]) { creditsUsed }
  issue_to_merge_request: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["issue_to_merge_request"]) { creditsUsed }
  recommend_reviewers: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["recommend_reviewers"]) { creditsUsed }
  resolve_sast_vulnerability: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["resolve_sast_vulnerability"]) { creditsUsed }
  sast_fp_detection: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["sast_fp_detection"]) { creditsUsed }
  secrets_fp_detection: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["secrets_fp_detection"]) { creditsUsed }
  security_analyst_agent: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["security_analyst_agent"]) { creditsUsed }
  security_review: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["security_review"]) { creditsUsed }
  software_development: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["software_development"]) { creditsUsed }
  ai_gateway_proxy_use: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["ai_gateway_proxy_use"]) { creditsUsed }
  ambient: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["ambient"]) { creditsUsed }

  # Secrets Manager
  secrets_stored: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["secrets_stored"]) { creditsUsed }
  secrets_read: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["secrets_read"]) { creditsUsed }

  # Orbit
  orbit_mcp: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["orbit_mcp"]) { creditsUsed }
  orbit_rest: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["orbit_rest"]) { creditsUsed }
  orbit_dws: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["orbit_dws"]) { creditsUsed }
  orbit_frontend: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["orbit_frontend"]) { creditsUsed }
  orbit_core: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["orbit_core"]) { creditsUsed }
  orbit_code_intelligence: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["orbit_code_intelligence"]) { creditsUsed }

  # Artifact Registry
  artifact_registry_component: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["artifact_registry_component"]) { creditsUsed }
  artifact_registry_storage: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["artifact_registry_storage"]) { creditsUsed }
  artifact_registry_egress: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["artifact_registry_egress"]) { creditsUsed }

  # Hosted Runners
  runner_compute_usage: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["runner_compute_usage"]) { creditsUsed }
}

The flow type list above reflects the available flow types as of GitLab 19.2. Run the discovery query in Step 2 to confirm which flow types are present for your namespace.

Step 4: Handle unavailable flow types

If the query returns an error because one or more flow types are not available, use the discovery query from Step 2 to identify the supported flow types, remove the unsupported aliases from the query, and run it again.

GitLab Dedicated and GitLab Self-Managed

On GitLab Dedicated and GitLab Self-Managed, you can query usage at the instance level (across all namespaces) or at the namespace level (scoped to a single top-level group).

Step 1: Open the GraphQL Explorer

Navigate to the GraphQL Explorer for your instance:

GitLab Dedicated: https://your-tenant.gitlab-dedicated.com/-/graphql-explorer
GitLab Self-Managed: https://your-gitlab-instance/-/graphql-explorer

Step 2: Discover available flow types (optional)

If you are unsure which flow types are available on your instance, run the following discovery query first.

For an instance-level query (requires instance administrator):

query getFlowTypes {
  subscriptionUsage {
    products {
      id
      title
      flowTypes {
        id
        title
      }
    }
  }
}

For a namespace-level query (requires Owner role on the top-level group), replace your-top-level-group with the path of your root group:

query getFlowTypes {
  subscriptionUsage(namespacePath: "your-top-level-group") {
    products {
      id
      title
      flowTypes {
        id
        title
      }
    }
  }
}

Use the id values returned by this query to build the per-feature query in the next step.

Step 3: Query GitLab Credits usage per feature

Run the appropriate query below to retrieve creditsUsed for each flow type in the current month. Each aliased field targets a single flow type so that the response contains one creditsUsed value per feature.

Instance-level query (omit namespacePath; requires instance administrator):

query getCreditsPerFlowType {
  # Duo Agent Platform
  ai_catalog_agent: subscriptionUsage(flowTypes: ["ai_catalog_agent"]) { creditsUsed }
  analytics_agent: subscriptionUsage(flowTypes: ["analytics_agent"]) { creditsUsed }
  chat: subscriptionUsage(flowTypes: ["chat"]) { creditsUsed }
  code_review: subscriptionUsage(flowTypes: ["code_review"]) { creditsUsed }
  code_suggestions: subscriptionUsage(flowTypes: ["code_suggestions"]) { creditsUsed }
  convert_to_gl_ci: subscriptionUsage(flowTypes: ["convert_to_gl_ci"]) { creditsUsed }
  dap_feature_legacy: subscriptionUsage(flowTypes: ["dap_feature_legacy"]) { creditsUsed }
  developer: subscriptionUsage(flowTypes: ["developer"]) { creditsUsed }
  duo_chat_classic: subscriptionUsage(flowTypes: ["duo_chat_classic"]) { creditsUsed }
  duo_planner: subscriptionUsage(flowTypes: ["duo_planner"]) { creditsUsed }
  fix_pipeline: subscriptionUsage(flowTypes: ["fix_pipeline"]) { creditsUsed }
  issue_to_merge_request: subscriptionUsage(flowTypes: ["issue_to_merge_request"]) { creditsUsed }
  recommend_reviewers: subscriptionUsage(flowTypes: ["recommend_reviewers"]) { creditsUsed }
  resolve_sast_vulnerability: subscriptionUsage(flowTypes: ["resolve_sast_vulnerability"]) { creditsUsed }
  sast_fp_detection: subscriptionUsage(flowTypes: ["sast_fp_detection"]) { creditsUsed }
  secrets_fp_detection: subscriptionUsage(flowTypes: ["secrets_fp_detection"]) { creditsUsed }
  security_analyst_agent: subscriptionUsage(flowTypes: ["security_analyst_agent"]) { creditsUsed }
  security_review: subscriptionUsage(flowTypes: ["security_review"]) { creditsUsed }
  software_development: subscriptionUsage(flowTypes: ["software_development"]) { creditsUsed }
  ai_gateway_proxy_use: subscriptionUsage(flowTypes: ["ai_gateway_proxy_use"]) { creditsUsed }
  ambient: subscriptionUsage(flowTypes: ["ambient"]) { creditsUsed }

  # Secrets Manager
  secrets_stored: subscriptionUsage(flowTypes: ["secrets_stored"]) { creditsUsed }
  secrets_read: subscriptionUsage(flowTypes: ["secrets_read"]) { creditsUsed }

  # Orbit
  orbit_mcp: subscriptionUsage(flowTypes: ["orbit_mcp"]) { creditsUsed }
  orbit_rest: subscriptionUsage(flowTypes: ["orbit_rest"]) { creditsUsed }
  orbit_dws: subscriptionUsage(flowTypes: ["orbit_dws"]) { creditsUsed }
  orbit_frontend: subscriptionUsage(flowTypes: ["orbit_frontend"]) { creditsUsed }
  orbit_core: subscriptionUsage(flowTypes: ["orbit_core"]) { creditsUsed }
  orbit_code_intelligence: subscriptionUsage(flowTypes: ["orbit_code_intelligence"]) { creditsUsed }

  # Artifact Registry
  artifact_registry_component: subscriptionUsage(flowTypes: ["artifact_registry_component"]) { creditsUsed }
  artifact_registry_storage: subscriptionUsage(flowTypes: ["artifact_registry_storage"]) { creditsUsed }
  artifact_registry_egress: subscriptionUsage(flowTypes: ["artifact_registry_egress"]) { creditsUsed }

  # Hosted Runners
  runner_compute_usage: subscriptionUsage(flowTypes: ["runner_compute_usage"]) { creditsUsed }
}

Namespace-level query (supply namespacePath; requires Owner role on the top-level group). Replace your-top-level-group with the path of your root group:

query getCreditsPerFlowType {
  # Duo Agent Platform
  ai_catalog_agent: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["ai_catalog_agent"]) { creditsUsed }
  analytics_agent: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["analytics_agent"]) { creditsUsed }
  chat: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["chat"]) { creditsUsed }
  code_review: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["code_review"]) { creditsUsed }
  code_suggestions: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["code_suggestions"]) { creditsUsed }
  convert_to_gl_ci: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["convert_to_gl_ci"]) { creditsUsed }
  dap_feature_legacy: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["dap_feature_legacy"]) { creditsUsed }
  developer: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["developer"]) { creditsUsed }
  duo_chat_classic: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["duo_chat_classic"]) { creditsUsed }
  duo_planner: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["duo_planner"]) { creditsUsed }
  fix_pipeline: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["fix_pipeline"]) { creditsUsed }
  issue_to_merge_request: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["issue_to_merge_request"]) { creditsUsed }
  recommend_reviewers: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["recommend_reviewers"]) { creditsUsed }
  resolve_sast_vulnerability: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["resolve_sast_vulnerability"]) { creditsUsed }
  sast_fp_detection: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["sast_fp_detection"]) { creditsUsed }
  secrets_fp_detection: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["secrets_fp_detection"]) { creditsUsed }
  security_analyst_agent: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["security_analyst_agent"]) { creditsUsed }
  security_review: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["security_review"]) { creditsUsed }
  software_development: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["software_development"]) { creditsUsed }
  ai_gateway_proxy_use: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["ai_gateway_proxy_use"]) { creditsUsed }
  ambient: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["ambient"]) { creditsUsed }

  # Secrets Manager
  secrets_stored: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["secrets_stored"]) { creditsUsed }
  secrets_read: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["secrets_read"]) { creditsUsed }

  # Orbit
  orbit_mcp: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["orbit_mcp"]) { creditsUsed }
  orbit_rest: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["orbit_rest"]) { creditsUsed }
  orbit_dws: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["orbit_dws"]) { creditsUsed }
  orbit_frontend: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["orbit_frontend"]) { creditsUsed }
  orbit_core: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["orbit_core"]) { creditsUsed }
  orbit_code_intelligence: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["orbit_code_intelligence"]) { creditsUsed }

  # Artifact Registry
  artifact_registry_component: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["artifact_registry_component"]) { creditsUsed }
  artifact_registry_storage: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["artifact_registry_storage"]) { creditsUsed }
  artifact_registry_egress: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["artifact_registry_egress"]) { creditsUsed }

  # Hosted Runners
  runner_compute_usage: subscriptionUsage(namespacePath: "your-top-level-group", flowTypes: ["runner_compute_usage"]) { creditsUsed }
}

The flow type list above reflects the available flow types as of GitLab 19.2. Run the discovery query in Step 2 to confirm which flow types are present on your instance.

Step 4: Handle unavailable flow types

If the query returns an error because one or more flow types are not available on your instance, use the discovery query from Step 2 to identify the supported flow types, remove the unsupported aliases from the query, and run it again.

Example response

A successful response looks like the following:

{
  "data": {
    "chat": {
      "creditsUsed": 12.5
    },
    "code_suggestions": {
      "creditsUsed": 4.0
    },
    "code_review": {
      "creditsUsed": 0.0
    }
  }
}

A creditsUsed value of 0.0 means no GitLab Credits were consumed by that flow type in the current month. A null value may indicate the flow type is not available.

Additional Information

The subscriptionUsage query defaults to the current calendar month. The billing period boundaries follow the subscription's billing cycle, which may differ from the calendar month. Refer to the GitLab Credits and usage billing documentation for details on billing period definitions.
The namespacePath argument must be the path of a top-level group (root namespace). Subgroup paths are not supported and return an error.
The GraphQL Explorer is available to any authenticated user, but the subscriptionUsage field returns data only for namespaces and instances where the caller has sufficient permissions.
The GitLab Credits dashboard provides a visual breakdown of GitLab Credits usage and is the recommended interface for most administrators. Use the GraphQL query when you need programmatic access or a breakdown that the dashboard does not expose.

How to View GitLab Credits Usage Per Feature Using GraphQL

Description

Impacted Offerings

Prerequisites

Solution

GitLab.com

Step 1: Open the GraphQL Explorer

Step 2: Discover available flow types (optional)

Step 3: Query GitLab Credits usage per feature

Step 4: Handle unavailable flow types

GitLab Dedicated and GitLab Self-Managed

Step 1: Open the GraphQL Explorer

Step 2: Discover available flow types (optional)

Step 3: Query GitLab Credits usage per feature

Step 4: Handle unavailable flow types

Example response

Additional Information

Related Links

On this page...