---
title: "GitHub Copilot Metrics"
canonical_url: "https://docs.getdx.com/connectors/github-copilot-metrics/"
md_url: "https://docs.getdx.com/connectors/github-copilot-metrics.md"
last_updated: "2026-06-18"
---
# GitHub Copilot Metrics
By enabling the GitHub Copilot connector, you can import user-level Copilot usage metrics. Please refer to the API documentation below and our [schema explorer](https://docs.getdx.com/schema/) to see what data DX imports—note that DX does not read or access your source code.
The connector supports both **enterprise-level** and **organization-level** (non-enterprise) Copilot usage metrics. Only one level is used per customer—enterprise and org data are never mixed. Choose the setup that matches your GitHub structure.
## Authentication methods
The GitHub Copilot connector supports three authentication methods:
- **Personal Access Token (PAT)**: Provides access to enterprise-level metrics, user-level metrics, and Copilot seat assignments. _Enterprise only._
- **GitHub App (Enterprise)**: Provides access to user-level metrics via the enterprise `users-1-day` API. _Enterprise only._
- **GitHub App (Organization)**: Provides access to user-level metrics via the org `users-1-day` API. _For non-enterprise customers or org-level data._
All methods import data into the same `github_copilot_daily_usages` table. Enterprise data is identified by `enterprise_slug`; org-level data is identified by `organization_id`.
**Note:** The Copilot seat assignments API is optional, as active users can be determined from the `users-1-day` metrics. This is why GitHub App authentication, which only accesses the `users-1-day` endpoint, provides complete user-level usage data without requiring the seat assignments API.
### GitHub App installation requirements
For detailed guidance on creating and installing GitHub Apps, see [Registering a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) and [Installing your own GitHub App](https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app).
**Enterprise-level GitHub App:**
- The GitHub App must be installed at the **enterprise level** (not organization level)
- The app requires `enterprise_copilot_metrics: read` permission
- Note that the enterprise-level metrics API and seat assignments API do not support GitHub App installation tokens, so only user-level daily metrics will be available
**Organization-level GitHub App (non-enterprise):**
- The GitHub App is installed at the **organization level** (no enterprise installation required)
- The app requires **Organization: Copilot metrics (read)** permission—see [GitHub's Copilot usage metrics documentation](https://docs.github.com/en/enterprise-cloud@latest/rest/copilot/copilot-usage-metrics?apiVersion=2022-11-28#get-copilot-organization-usage-metrics-for-a-specific-day)
- DX iterates over your app installations and pulls metrics per organization using `GET /orgs/{org}/copilot/metrics/reports/users-1-day`
- Org-level connection creation fails if enterprise-level data already exists for your account; similarly, org import is skipped if enterprise-level data exists
## Prerequisites
**For enterprise-level connections (PAT or Enterprise GitHub App):**
- a GitHub user account that is an [Enterprise Owner](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise#enterprise-owners)
- a [Copilot metrics API access policy](https://docs.github.com/en/copilot/rolling-out-github-copilot-at-scale/analyzing-usage-over-time-with-the-copilot-metrics-api#prerequisites) that is set to [**Enabled everywhere**](https://docs.github.com/en/enterprise-cloud@latest/rest/copilot/copilot-usage-metrics?apiVersion=2022-11-28)
- allowlist [DX IP addresses](https://docs.getdx.com/allowlisting-dx/) if your GitHub instance is behind a firewall or has IP restrictions. IP allowlisting must be configured at the enterprise level, not just the org-level, to avoid `internal_error` connection issues.
**For organization-level connections (non-enterprise GitHub App):**
- a GitHub user account that is an [Organization owner](https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#organization-owners)
- a [Copilot metrics API access policy](https://docs.github.com/en/copilot/rolling-out-github-copilot-at-scale/analyzing-usage-over-time-with-the-copilot-metrics-api#prerequisites) enabled for each organization (manage at `https://github.com/organizations/ORGANIZATION_NAME/settings/copilot/policies`)
- allowlist [DX IP addresses](https://docs.getdx.com/allowlisting-dx/) if your GitHub instance is behind a firewall or has IP restrictions
## Setup instructions
Follow the steps below to connect GitHub to DX using your preferred authentication method.
### Option 1: Personal Access Token (PAT)
This method provides access to all available Copilot metrics APIs.
#### Step 1
While signed into GitHub as an Enterprise Owner, navigate to **Settings > Developer Settings > Personal Access Token**.
#### Step 2
Click on **Token (classic) > Generate new token (Classic)**. Either the manage_billing:copilot or read:enterprise scope is required.
#### Step 3
- Navigate to the connections page in DX and select "+ Connection" in the top right.
- Enter the credentials you have generated in the previous steps—refer to the information below for errors and troubleshooting.
### Option 2: GitHub App (Enterprise)
This method provides access to user-level metrics only for enterprise customers.
#### Step 1
Create a GitHub App at the enterprise level with the following permission:
- `enterprise_copilot_metrics: read`
#### Step 2
Install the GitHub App at the **enterprise level**. The installation must be at the enterprise level (not organization level) to access Copilot metrics.
#### Step 3
Navigate to the connections page in DX and select "+ Connection" in the top right. Select GitHub App authentication and enter your installation credentials.
### Option 3: GitHub App non-enterprise
This method is for organizations that do not use GitHub Enterprise. It provides access to user-level metrics via the org-level API. Follow the full [GitHub App registration and installation process](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app).
#### Step 1
Browse to the URL below with ORGANIZATION_NAME replaced:
```
https://github.com/organizations/ORGANIZATION_NAME/settings/apps/new?public=false&url=https://getdx.com&request_oauth_on_install=false&setup_on_update=false&webhook_active=false
```
#### Step 2
This will pre-populate settings. Enter a name for your GitHub App (e.g. **[COMPANYNAME] DX - GitHub Copilot**). In the **Permissions & events** tab, set the following permission:
| Scope | Permission | Description |
| ------------ | --------------- | ---------------------- |
| Organization | Copilot metrics | Read-only _(required)_ |
See [GitHub's Copilot usage metrics documentation](https://docs.github.com/en/enterprise-cloud@latest/rest/copilot/copilot-usage-metrics?apiVersion=2022-11-28#get-copilot-organization-usage-metrics-for-a-specific-day) for details.
#### Step 3
Scroll to the bottom of the page and click **Create GitHub App**.
#### Step 4
The GitHub App ID will be shown at the top of the subsequent screen. Copy this ID for use in DX later.
{class="max-w-xl mx-auto"}
#### Step 5
On the same screen, scroll down to **Private keys** and click **Generate a private key** to download a PEM file. Copy the contents of this file for use in DX later.
{class="max-w-xl mx-auto"}
#### Step 6
Click **Install App** in the sidebar, then click **Install** beside each organization where you want Copilot metrics. No enterprise installation is required.
{class="max-w-xl mx-auto"}
#### Step 7
Navigate to the connections page in DX and select "+ Connection" in the top right. Select GitHub App authentication and enter your App ID and private key.
**Note:** If you already have enterprise-level Copilot data in DX, org-level connection creation will fail. Use either enterprise-level or org-level connections, not both.
## API reference
The table below lists the specific API endpoints that are used by DX. Please note that, to access these API endpoints, your Copilot Metrics API access policy must be enabled or set to "no policy" for your enterprise or organization.
| Endpoint | Reference |
|----------------------------------------------------------------|-----------|
| /enterprises/{enterprise}/copilot/billing/seats | [Link](https://docs.github.com/en/enterprise-cloud@latest/rest/copilot/copilot-user-management?apiVersion=2022-11-28#list-all-copilot-seat-assignments-for-an-enterprise) (PAT only, optional, enterprise) |
| /enterprises/{enterprise}/copilot/metrics/reports/users-1-day | [Link](https://docs.github.com/en/enterprise-cloud@latest/rest/copilot/copilot-usage-metrics?apiVersion=2022-11-28#get-copilot-users-usage-metrics-for-a-specific-day) (PAT and GitHub App, enterprise) |
| /orgs/{org}/copilot/metrics/reports/users-1-day | [Link](https://docs.github.com/en/enterprise-cloud@latest/rest/copilot/copilot-usage-metrics?apiVersion=2022-11-28#get-copilot-organization-usage-metrics-for-a-specific-day) (GitHub App, org-level only) |
## Errors
The table below lists potential error codes when adding a connection in DX.
| Error | Description |
|----------------------|------------------------------------------------------------------------------------------------------------------|
| `invalid_credentials` | Your API credentials entered are not valid. |
| `invalid_permissions` | Your API token or GitHub App does not have the permissions required by DX. For enterprise: verify your service account is an [Enterprise Owner](https://docs.github.com/en/enterprise-cloud@latest/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/roles-in-an-enterprise#enterprise-owners). For org-level: verify your GitHub App has **Organization: Copilot metrics (read)** and is installed to the organization. |
## Curl commands
#### When connection verification fails
When DX verifies a GitHub Copilot connection, it checks access to the relevant endpoints. If your connection is failing, you can test the endpoints directly using the curl commands below to troubleshoot the issue.
**Enterprise (PAT):** Replace `YOUR_ENTERPRISE_SLUG` with your enterprise slug and `YOUR_TOKEN` with your Personal Access Token.
**Org-level (GitHub App):** Replace `YOUR_ORG` with your organization login and `YOUR_INSTALLATION_TOKEN` with an [installation access token](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app) from your GitHub App.
#### 1. Test Copilot Seat Assignments Access (enterprise PAT only)
This verifies that your token can access Copilot seat assignments:
#### 2. Test Copilot User 1-Day Usage Metrics (enterprise)
This verifies that your token can access daily user-level Copilot usage metrics. Replace `YYYY-MM-DD` with the date you want to inspect:
#### 3. Test Copilot User 1-Day Usage Metrics (org-level)
For org-level connections, test the organization API. Replace `YOUR_ORG` with your organization login and `YOUR_INSTALLATION_TOKEN` with an installation access token:
## Troubleshooting
#### I'm seeing "no_resource" error from API response
This indicates that you don't have admin access to the enterprise or organization account. Use the curl commands above to verify access to the required endpoints.
#### Copilot has been connected but all of my reports are blank
This indicates that a [Copilot metrics API access policy](https://docs.github.com/en/copilot/rolling-out-github-copilot-at-scale/analyzing-usage-over-time-with-the-copilot-metrics-api#prerequisites) has not yet been enabled for your enterprise or organization. For org-level connections, enable it per organization at `https://github.com/organizations/ORGANIZATION_NAME/settings/copilot/policies`.
#### Org-level connection fails with "enterprise data exists" or similar
You cannot use both enterprise-level and org-level Copilot connections for the same DX account. If enterprise-level data already exists, org-level connection creation will fail. Use one connection type only.
---
## Sitemap
[Overview of all docs pages](/llms.txt)