AI usage events

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

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 fields

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

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)

Dimensions

Metrics

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:

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