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

analytics

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"
```

Was this page helpful?