Add 'Team-level Copilot usage metrics' reference doc (#61203)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Eric Hollenberry <hollenberry@users.noreply.github.com>

Author: 3 people

content/copilot/concepts/copilot-usage-metrics/copilot-metrics.md

@@ -138,3 +138,4 @@ Now that you understand what each {% data variables.product.prodname_copilot_sho
 * To view adoption and usage trends across your enterprise and organizations, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/view-usage-and-adoption).
 * To analyze how code is being generated by users and agents, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/view-code-generation).
 * To access {% data variables.product.prodname_copilot_short %} usage metrics programmatically, see [AUTOTITLE](/rest/copilot/copilot-usage-metrics).
+* To construct team-level metrics by aggregating per-user records, see [AUTOTITLE](/copilot/reference/copilot-usage-metrics/team-level-metrics).

content/copilot/reference/copilot-usage-metrics/copilot-usage-metrics.md

@@ -18,6 +18,7 @@ The {% data variables.product.prodname_copilot_short %} usage metrics dashboard
 
 * The {% data variables.product.prodname_copilot_short %} usage metrics dashboards are available at the **enterprise** and **organization** level.
 * The {% data variables.product.prodname_copilot_short %} usage metrics APIs support **enterprise-, organization-, and user-level** records.
+* Team-level metrics are not pre-aggregated; you construct them by joining the user-teams report with the per-user usage metrics report. See [AUTOTITLE](/copilot/reference/copilot-usage-metrics/team-level-metrics).
 
 For guidance on how to read and interpret these metrics, see [AUTOTITLE](/copilot/concepts/copilot-metrics).
 
@@ -143,3 +144,18 @@ These fields capture daily pull request creation, review, merge, and suggestion
 | `pull_requests.total_copilot_suggestions` | Number of pull request review suggestions generated by {% data variables.product.prodname_copilot_short %} on this specific day. |
 | `pull_requests.total_copilot_applied_suggestions` | Number of pull request review suggestions generated by {% data variables.product.prodname_copilot_short %} that were applied on this specific day. |
 | `pull_requests.copilot_suggestions_by_comment_type` | Aggregated counts of {% data variables.product.prodname_copilot_short %} code review suggestions, broken down by the comment type {% data variables.product.prodname_copilot_short %} assigned (for example, `security` or `bug_risk`). Each entry includes `comment_type`, `total_copilot_suggestions`, and `total_copilot_applied_suggestions`. Not available at the repository level. |
+
+### User-teams fields (API only)
+
+These fields appear in the daily user-teams report (available via REST API at the organization and enterprise scopes) and are used to construct team-level metrics by joining with the per-user usage metrics report. For the full join recipe and the endpoint URLs, see [AUTOTITLE](/copilot/reference/copilot-usage-metrics/team-level-metrics).
+
+Teams with fewer than 5 seated {% data variables.product.prodname_copilot_short %} users on a given day are excluded from the user-teams report.
+
+| Field | Description |
+|:--|:--|
+| `user_id` / `user_login` | Unique identifier and {% data variables.product.github %} username for the user. |
+| `day` | Calendar day this record represents. |
+| `organization_id` (organization scope) | Unique ID of the organization the team belongs to. |
+| `enterprise_id` (enterprise scope) | Unique ID of the enterprise the team belongs to. The enterprise-scoped report includes both enterprise teams and business teams. |
+| `team_id` | Unique ID of the team the user belongs to. |
+| `slug` | URL-friendly identifier for the team. |

content/copilot/reference/copilot-usage-metrics/example-schema.md

@@ -249,3 +249,70 @@ The following are example schemas for the user-level and enterprise-level data r
   "entity_id_partition" : 2
 } ]
 ```
+
+The following user-teams report examples are returned by the `user-teams-1-day` endpoints and are intended to be joined with the per-user usage report on `user_id`, `day`, and the relevant entity id (`organization_id` for the organization scope, `enterprise_id` for the enterprise scope) to derive team-level metrics. For more guidance, see [AUTOTITLE](/copilot/reference/copilot-usage-metrics/team-level-metrics).
+
+> [!NOTE]
+> Teams with fewer than 5 seated {% data variables.product.prodname_copilot_short %} users are omitted from user-teams reports.
+
+## Organization user-teams schema example
+
+```json copy
+[
+  {
+    "user_id": 1001,
+    "user_login": "octocat",
+    "day": "2026-05-14",
+    "organization_id": "999",
+    "team_id": 42,
+    "slug": "frontend"
+  },
+  {
+    "user_id": 1001,
+    "user_login": "octocat",
+    "day": "2026-05-14",
+    "organization_id": "999",
+    "team_id": 43,
+    "slug": "backend"
+  },
+  {
+    "user_id": 1002,
+    "user_login": "hubot",
+    "day": "2026-05-14",
+    "organization_id": "999",
+    "team_id": 42,
+    "slug": "frontend"
+  }
+]
+```
+
+## Enterprise user-teams schema example
+
+```json copy
+[
+  {
+    "user_id": 1001,
+    "user_login": "octocat",
+    "day": "2026-05-14",
+    "enterprise_id": "1",
+    "team_id": 9001,
+    "slug": "eng-platform"
+  },
+  {
+    "user_id": 1001,
+    "user_login": "octocat",
+    "day": "2026-05-14",
+    "enterprise_id": "1",
+    "team_id": 7001,
+    "slug": "business-analytics"
+  },
+  {
+    "user_id": 1002,
+    "user_login": "hubot",
+    "day": "2026-05-14",
+    "enterprise_id": "1",
+    "team_id": 9001,
+    "slug": "eng-platform"
+  }
+]
+```

content/copilot/reference/copilot-usage-metrics/index.md

@@ -9,6 +9,7 @@ children:
   - /interpret-copilot-metrics
   - /reconciling-usage-metrics
   - /lines-of-code-metrics
+  - /team-level-metrics
   - /example-schema
 contentType: reference
 ---

content/copilot/reference/copilot-usage-metrics/interpret-copilot-metrics.md

@@ -74,3 +74,4 @@ Use trends in usage, feature adoption, and language activity to guide enablement
 ## Next steps
 
 * To access metrics programmatically, including enterprise, organization, and user-level records, see [AUTOTITLE](/rest/copilot/copilot-usage-metrics).
+* To construct team-level metrics from the per-user usage metrics report, see [AUTOTITLE](/copilot/reference/copilot-usage-metrics/team-level-metrics).

content/copilot/reference/copilot-usage-metrics/reconciling-usage-metrics.md

@@ -20,6 +20,7 @@ The {% data variables.product.prodname_copilot_short %} usage metrics dashboard,
 
 * The {% data variables.product.prodname_copilot_short %} usage metrics dashboards are available at the **enterprise** and **organization** level.
 * The {% data variables.product.prodname_copilot_short %} usage metrics APIs support **enterprise-, organization-, and user-level** records.
+* Team-level totals are not pre-aggregated. They are constructed by joining the user-teams report with the per-user usage metrics report. See [AUTOTITLE](/copilot/reference/copilot-usage-metrics/team-level-metrics).
 
 ## Prerequisite