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.

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