REST API endpoints for user-level feature engagement metrics

Introduction

The user-level feature engagement API allows you to see a picture of individuals' adoption and sustained engagement patterns with Copilot features. GitHub designed the API to help companies accomplish two main things:

Track and encourage sustained engagement with Copilot, across all its features, which is a common factor in companies that get the most benefit from Copilot
Identify and respond to a lack of knowledge about available features among users

The metrics will allow you to maximize the benefits of Copilot by capitalizing on your successes and taking direct action on your biggest opportunities. By summing engagement across features over time, you can:

Find gaps in awareness (if features show no or little use)
Identify champions (users with consistent, broad engagement with features)
Identify users who need additional training (lagging, low engagement over time)

By supplying these metrics at a user level, by login, we intend to enable you to map proficiency with Copilot to your org chart and cost centers. You will be able to extract further organizational insights in conjunction with your DevOps data and other sources of engineering metrics.

Prerequisites

To access this endpoint, the Copilot Metrics API access policy must be enabled or set to "no policy" for the enterprise within GitHub settings. Only enterprise owners and billing managers can view Copilot user engagement for the enterprise.

About the API

For a given user, on a given day, the API provides a list of Copilot features and a 0/1 boolean which describes whether the user interacted with that feature on that day.

In the private preview, the report includes the following features:

Copilot in the CLI
IDE code completions
Code Review
Chat in GitHub.com
IDE inline chat
Knowledge base chat
Chat in GitHub Mobile
IDE panel chat
Copilot for pull requests

We are evaluating options for including extensions, Copilot edits, and agents in a future update.

The API provides data for up to 28 days of history. For each day of data, the report will return data in the following format:

...
{"day": "2025-01-01T00:00:00.0000000Z", "login": "github_login0", "user_id": 198650010, "cli_engagement": 0, "code_completion_engagement": 1, "code_review_engagement": 0, "dotcom_chat_engagement": 0, "inline_chat_engagement": 0, "knowledge_base_chat_engagement": 0, "mobile_chat_engagement": 0, "panel_chat_engagement": 0, "pull_request_summary_engagement": 0 }
{"day": "2025-01-01T00:00:00.0000000Z", "login": "github_login1", "user_id": 198650011, "cli_engagement": 0, "code_completion_engagement": 1, "code_review_engagement": 0, "dotcom_chat_engagement": 0, "inline_chat_engagement": 0, "knowledge_base_chat_engagement": 0, "mobile_chat_engagement": 0, "panel_chat_engagement": 0, "pull_request_summary_engagement": 0 }
...

Data definitions

day: the day.
login: the login of the Copilot user, used to log in to GitHub.
user_id: unique id of the user.
cli_engagement: prompting Copilot in the CLI at least once.
code_completions_engagement: accepting an inline code suggestion from ghost text, in partial or full, at least once.
code_review_engagement: initiating a Copilot code review at least once.
dotcom_chat_engagement: prompting Copilot chat in GitHub.com at least once.
inline_chat_engagement: prompting Copilot panel chat at least once.
knowledge_base_chat_engagement: prompting Copilot knowledge base chat at least once.
mobile_chat_engagement: prompting Copilot in the iOS Mobile app at least once.
panel_chat_engagement: prompting Copilot panel chat at least once.
pull_request_summary_engagement: generate a PR summary using the Summary option in Copilot PRs at least once, or use PR Chat at least once.

About the data

Why this data pattern?

It cannot be easily gamed with spam and helps avoid injecting adverse incentives to our customers’ organizations.
It aligns with research done on how to consistently capture the greatest systemic value from Copilot through sustained engagement with the breadth and depth of available features.
It creates clear, explicit, and constructive calls to action whether through identifying onboarding and enablement opportunities, informing license management, or identifying power usage.

Why not supply granular usage stats like lines of code?

We avoid granular usage metrics at the individual level because they are easy to game, and historically lead individuals to optimize their own behavior for the metric, rather than the productive practice.
Low-level usage metrics for individuals lead to focus on the wrong goals and risk introducing toxic anti-patterns to Copilot use.

What counts as engagement?

We consider a user to be engaged with Copilot when we observe an intentful interaction with a Copilot feature. In practice this means accepting a code suggestion (not merely receiving one), sending a prompt to Chat, or triggering a Pull Request summary, for example. We do not consider authentication, or passive events such as the receipt of ‘ghost text’ in the editor as engagement.

How much engagement will a user show?

A user will never show a value greater than “1” for a given day, for a given feature.

What kinds of views should I try, to get started?

Some easy views to get started include:

Sum all values for each feature column to see the overall utilization of each Copilot feature.
Sum all feature columns by user to find the most engaged power users of each.

Get Copilot user engagement data for an enterprise

GET /enterprises/{enterprise}/copilot/user-engagement

Use this endpoint to retrieve a breakdown of user engagement for GitHub Copilot by feature. User engagement reports are processed once per day for the previous day, and the response will only include data up until yesterday. The response contains user engagement reports for up to 28 days in the past. In order for an end user to be counted towards these engagement metrics, they must have telemetry enabled in their IDE.

OAuth app tokens and personal access tokens (classic) need either the manage_billing:copilot or read:enterprise scopes to use this endpoint.

Headers

Name	Type	Description
`accept`	string	Setting to `application/vnd.github+json` is recommended.

Path parameters

Name	Type	Required	Description
`enterprise`	string	Yes	The slug version of the enterprise name. You can also substitute this value with the enterprise id.

Query parameters

Name	Type	Description
`since`	string	The date from which to start returning user engagement data, in ISO 8601 format: YYYY-MM-DD. Cannot be more than 28 days in the past.
`until`	string	The date until which to return user engagement data, in ISO 8601 format: YYYY-MM-DD.

HTTP response status codes

Status code	Description
`200`	OK
`403`	Forbidden
`404`	Not found
`422`	Either date parameters are invalid, the since date is more than 28 days in the past, the since date is after the until date, or the Copilot Metrics API policy is disabled
`500`	Internal server error

Example response

Status: 200

[
  {
    "date": "2025-01-29",
    "blob_uri": "https://copilotengagement.blob.core.windows.net/reports/12345/2025-01-29.json?sv=2023-01-03&st=2025-02-11T18%3A04%3A32Z&se=2025-02-12T18%3A04%3A32Z&skoid=e75afe26-d735-42b3-a23c-82b76fbbc282&sktid=398a6654-997b-47e9-b12b-9515b896b4de&skt=2025-02-11T18%3A04%3A32Z&ske=2025-02-12T18%3A04%3A32Z&sks=b&skv=2023-01-03&sr=b&sp=r&sig=A%2F58z2IOvYPRhAO5gQ4loGtflsfDwwgU1VwPC7Px1qQ%3D"
  }
]

Code Samples

cURL

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/copilot/user-engagement

JavaScript

// Octokit.js
// https://github.com/octokit/core.js#readme
const octokit = new Octokit({
  auth: 'YOUR-TOKEN'
})

await octokit.request('GET /enterprises/{enterprise}/copilot/user-engagement', {
  enterprise: 'ENTERPRISE',
  headers: {
    'X-GitHub-Api-Version': '2022-11-28'
  }
})

GitHub CLI

# GitHub CLI api
# https://cli.github.com/manual/gh_api

gh api \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /enterprises/ENTERPRISE/copilot/user-engagement

Response schema

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "date": {
        "type": "string",
        "format": "date",
        "description": "The date for which this engagement data applies"
      },
      "blob_uri": {
        "type": "string",
        "format": "uri",
        "description": "The URI for the detailed engagement data"
      }
    },
    "required": [
      "date",
      "blob_uri"
    ]
  }
}

Troubleshooting issues with Copilot engagement data

Why do some users not show engagement, despite using Copilot?

This data relies on telemetry from the Copilot client. If a user has disabled telemetry in their IDE, their usage will not appear in the engagement table.
Network or firewall settings can potentially interfere with client telemetry.
If there is a consistent discrepancy between a user’s engagement history and their known activity, review the settings in their IDE to ensure that telemetry is enabled.
For more on this see Visual Studio, VSCode, or JetBrains resources, accordingly.

Why do some days not have reports?

If there is no logged engagement within an organization on a given day, then no report is generated for that day.

Why do some users not appear in the report?

Users who have no logged engagement on a given day do not appear in the report.

Differences between the API preview and technical preview contents

Several fields from the technical preview report have been deprecated. These include:

custom_model_engagement: model customization is in preview status, and we are working with the team to ensure that the necessary data is available. We hope to reintroduce this field in the future.
diff_chat_engagement: this field has been merged with pull_request_engagement.
ios_chat_engagement and android_chat_engagement: these fields have been merged into mobile_chat_engagement.
docs_chat_engagement has been renamed to knowledge_base_chat_engagement for clarity.

REST API endpoints for user-level feature engagement metrics

In this article