Help us learn about your current experience with the documentation. Take the survey.

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.

For more information, see scopes.

Query fields

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

Event

Description: Filter by the event identifier.

Allowed value types:

String
List (use in operator for multiple values)

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 operator for multiple values)

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 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.
Timestamp	`timestamp`	Group by date. Accepts a `granularity` parameter of `daily`, `weekly`, or `monthly` (default: `weekly`). For example, `timestamp(daily)`.
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.
Users count	`usersCount`	Number of unique users.

Notes:

The returningUsersCount and previousPeriodUsersCount metrics are only valid when the timestamp dimension is also selected.

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:

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

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

Events per user for a specific project:

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

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