Docs for 'Add AI credits per user to the usage metrics API [GA]' (#61936)

Author: jc-clark

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

@@ -67,7 +67,7 @@ These fields appear in the exported NDJSON reports and in the {% data variables.
 
 Reports come in different shapes depending on their scope and granularity, so the fields available in a record depend on which report it comes from:
 
-* **Per-user reports** (`*-users-1-day` and `*-users-28-day`) contain one record per user, including `user_id`, `user_login`, the `used_*` indicators, and `ai_adoption_phase`. They do not contain active-user counts, `pull_requests`, or `totals_by_ai_adoption_phase`.
+* **Per-user reports** (`*-users-1-day` and `*-users-28-day`) contain one record per user, including `user_id`, `user_login`, `ai_credits_used`, the `used_*` indicators, and `ai_adoption_phase`. They do not contain active-user counts, `pull_requests`, or `totals_by_ai_adoption_phase`.
 * **Aggregated reports** (`enterprise-1-day` and `org-1-day`) contain one aggregated record per enterprise or organization, including active-user counts, `pull_requests`, and `totals_by_ai_adoption_phase`. They do not contain `user_id`, `user_login`, or the `used_*` indicators.
 * **28-day reports** (`enterprise-28-day` and `org-28-day`) wrap an array of daily aggregated records in a `day_totals` field, with the reporting window at the top level.
 * **User-teams reports** (`*-user-teams-1-day`) map users to the teams they belong to, so you can construct team-level metrics.
@@ -96,6 +96,7 @@ Per-user reports contain one record per user for the reporting period. The 28-da
 |:--|:--|:--|:--|
 | `user_id` | `integer` | No | Unique identifier for the user. |
 | `user_login` | `string` | No | {% data variables.product.github %} username for the user. |
+| `ai_credits_used` | `number` | No | Total AI credits consumed by the user in the reporting period. This field is included in per-user reports only and is not broken down by feature, model, or surface. This metric is for consumption analysis, not invoicing totals. |
 | `user_initiated_interaction_count` | `integer` | No | Number of explicit prompts sent to {% data variables.product.prodname_copilot_short %}.<br><br>Only counts messages or prompts actively sent to the model. Does **not** include opening the chat panel, switching modes (for example, ask, edit, plan, or agent), using keyboard shortcuts to open the inline UI, or making configuration changes. |
 | `code_generation_activity_count` | `integer` | No | Number of distinct {% data variables.product.prodname_copilot_short %} output events generated. <br><br> **Includes:** All generated content, including comments and docstrings. <br> **Multiple blocks:** Each distinct code block from a single user prompt counts as a separate generation. <br> **Note:** This metric is not directly comparable to `user_initiated_interaction_count`, since one prompt can produce multiple generations. |
 | `code_acceptance_activity_count` | `integer` | No | Number of suggestions or code blocks accepted by users. <br><br> **Counts:** All built-in accept actions, such as “apply to file,” “insert at cursor,” “insert into terminal,” and use of the **Copy** button. <br> **Does not count:** Manual OS clipboard actions (for example, <kbd>Ctrl</kbd>+<kbd>C</kbd>). <br> **Granularity:** Each acceptance action increments the count once, regardless of how many code blocks were generated by the initial prompt. |

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

@@ -19,6 +19,7 @@ The following are example schemas for the user-level and enterprise-level data r
 
 ```json copy
 [{
+  "ai_credits_used": 12.5,
   "code_acceptance_activity_count": 1,
   "code_generation_activity_count": 1,
   "day": "2025-10-01",