AI usage events

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

AI usage events is a data source that provides aggregated metrics about GitLab Duo feature usage across your project or group.

Allowed modes

Allowed scopes

Scope Description
project Query AI usage events in a specific project.
group Query AI usage events across all projects in a group, including subgroups.

To aggregate AI usage events across multiple groups or projects, use a list with the in operator. For more information, see multiple groups and projects.

Query filters

Use these fields in the query parameter to filter your results.

Field Name Operators
Event event =, !=, in, not in
Feature feature =, !=, in, not in
Features count featuresCount >, <, >=, <=
Timestamp timestamp =, >, <, >=, <=
User user =, !=, in, not in

Event

Description: Filter by the event identifier.

Allowed value types:

  • String
  • List (use in or not in operator for multiple values)

Notes:

  • Excluding an event identifier that GitLab does not recognize excludes nothing. Validation of event identifiers is proposed in issue 629846.

Feature

Description: Filter by the GitLab Duo feature that generated the event. For example, code_suggestions or chat.

Allowed value types:

  • String
  • List (use in or not in operator for multiple values)

Notes:

  • != and not in return only events whose feature is known. Events that GitLab could not map to a feature are left out, so feature != "chat" is not the same as every event except chat.

Features count

Description: Filter by the number of unique features used. This filter is only valid when the featuresCount metric is also selected.

Allowed value types: Number

Timestamp

Description: Filter by when the event occurred. Use range operators to define a time window.

Allowed value types:

  • AbsoluteDate (in the format YYYY-MM-DD)
  • RelativeDate (in the format <sign><digit><unit>, where sign is +, -, or omitted, digit is an integer, and unit is one of d (days), w (weeks), m (months) or y (years))

Notes:

  • For the = operator, the time range is considered from 00:00 to 23:59 in the user’s time zone.

User

Description: Filter by the user who triggered the event.

Allowed value types:

  • Number (user ID)
  • List (use in or not in operator for multiple user IDs)

Support for username filtering is being tracked in issue 599750.

Dimensions

Dimension Name Description
Event event Group by event identifier.
Feature feature Group by GitLab Duo feature.
Group group Group by group. Accepts a depth parameter counted from the top-level group, from 1 to 99 (default: 1), so group returns top-level groups and group(depth=2) their subgroups. Events above that depth, or in a project at that depth rather than in a subgroup (for example, a project directly under the top-level group when depth=2), have no group, and the result can contain more than one row with no group.
Timestamp timestamp Group by date. Accepts a granularity parameter of daily, weekly, monthly, or a number of days such as 30d (default: weekly), and an optional origin. For example, timestamp(daily) or timestamp(granularity=30d, origin=2026-07-16).
User user Group by user (displays avatar, name, and username).

Metrics

Metric Name Description
Features count featuresCount Number of unique features used.
Previous period users count previousPeriodUsersCount Number of unique users in the previous period.
Returning users count returningUsersCount Number of users active in both the current and previous period.
Total count totalCount Total number of events, optionally filtered by event. Accepts an optional event parameter with one or more event identifiers (the same values as the event filter), for example totalCount(event="publish_duo_code_review_comments") or totalCount(event=["request_review_duo_code_review_on_mr_by_author", "request_review_duo_code_review_on_mr_by_non_author"]). Without the parameter, or with event=[], all events are counted. An event identifier that GitLab does not recognize returns an error.
Users count usersCount Number of unique users.

Notes:

  • The returningUsersCount and previousPeriodUsersCount metrics compare each timestamp bucket with the preceding one, so the timestamp dimension must also be selected. Without it, the query returns an error. A timestamp filter alone is not enough.

Sort fields

Sort by any field included in your selected dimensions or metrics. For more information, see analytics mode sorting.

Examples

  • Feature adoption for the last 30 days:

    yaml 
    ```glql
title: "GitLab Duo feature adoption (last 30 days)"
display: table
mode: analytics
query: type = AiUsageEvent and group = "gitlab-org" and timestamp > -30d
dimensions: feature as "Feature"
metrics: totalCount as "Total events", usersCount as "Users"
sort: usersCount desc
```

  • Weekly usage trend with returning users:

    yaml 
    ```glql
title: "Weekly GitLab Duo usage trend"
display: table
mode: analytics
query: type = AiUsageEvent and group = "gitlab-org" and timestamp > -30d
dimensions: timestamp(weekly) as "Week"
metrics: usersCount as "Users", returningUsersCount as "Returning users", previousPeriodUsersCount as "Previous period users"
sort: timestamp desc
```

  • Weekly GitLab Duo Code Review counts, one per event group:

    yaml 
    ```glql
title: "Weekly GitLab Duo Code Review requests and reviews"
display: table
mode: analytics
query: type = AiUsageEvent and group = "gitlab-org" and timestamp > -30d
dimensions: timestamp(weekly) as "Week"
metrics: totalCount(event=["request_review_duo_code_review_on_mr_by_author", "request_review_duo_code_review_on_mr_by_non_author"]) as "Requested", totalCount(event="publish_duo_code_review_comments") as "With comments", totalCount(event="find_no_issues_duo_code_review_after_review") as "Without comments"
sort: timestamp desc
```

  • Events per user for a specific project:

    yaml 
    ```glql
title: "GitLab Duo events by user"
display: table
mode: analytics
query: type = AiUsageEvent and project = "gitlab-org/gitlab" and timestamp > -30d
dimensions: user as "User"
metrics: totalCount as "Total events"
sort: totalCount desc
limit: 10
```

  • Overall unique users, without grouping:

    yaml 
    ```glql
title: "Unique GitLab Duo users (last 30 days)"
display: table
mode: analytics
query: type = AiUsageEvent and group = "gitlab-org" and timestamp > -30d
metrics: usersCount as "Users"
```