Document totals_by_client in Copilot usage metrics reference (#64343)

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Sophie <29382425+sophietheking@users.noreply.github.com>
Copilot-Session: cb13cece-3881-44f0-9dc6-33bef256bf38
Copilot-Session: fca8f742-dcf5-431b-9aa0-24c67b18f7b0
Copilot-Session: 325c6fa3-1aec-4b97-8f9a-145f91cd2d23

Author: 3 people

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

@@ -139,6 +139,7 @@ Per-user reports contain one record per user for the reporting period. The 28-da
 | `totals_by_cli` | `object` | Yes | CLI-specific metrics for the user. Omitted when the user had no {% data variables.copilot.copilot_cli_short %} usage that day. See [{% data variables.copilot.copilot_cli_short %} metrics fields](#copilot-cli-metrics-fields). |
 | `totals_by_copilot_app` | `object` | Yes | The {% data variables.copilot.github_copilot_app_short %} metrics for the user. Omitted when the user did not use the {% data variables.copilot.github_copilot_app_short %} that day. See [Metrics fields for the {% data variables.copilot.github_copilot_app_short %}](#copilot-app-metrics-fields). |
 | `totals_by_3rd_party_agent` | `array` | Yes | Per-agent usage metrics for recognized {% data variables.copilot.agent_apps %}. Omitted when the user had no recognized {% data variables.copilot.agent_app %} activity during the reporting period. See [{% data variables.copilot.agent_apps_caps %} metrics fields](#agent-apps-metrics-fields). |
+| `totals_by_client` | `array` | No | Per-client breakdown of the user's successful model requests and token usage, counted server-side. The array is always present and is empty when there is no usage to report. See [Client metrics fields](#client-metrics-fields). |
 | `totals_by_vscode_agent` | `object` | Yes | Dedicated {% data variables.product.prodname_vscode_shortname %} Agents-window metrics for the user. Omitted when both required counts are not available. See [{% data variables.product.prodname_vscode_shortname %} Agents-window metrics fields](#vs-code-agents-window-metrics-fields). |
 | `totals_by_ide` | `array` | No | Per-IDE breakdown of the user's activity. See [Activity breakdown objects](#activity-breakdown-objects). |
 | `totals_by_feature` | `array` | No | Per-feature breakdown of the user's activity. See [Activity breakdown objects](#activity-breakdown-objects). |
@@ -203,6 +204,7 @@ Activity totals and breakdowns:
 | `totals_by_cli` | `object` | Yes | Aggregated {% data variables.copilot.copilot_cli_short %} metrics for the day. Omitted when there is no CLI usage that day. Unlike the per-user form, it does not include `last_known_cli_version`. See [{% data variables.copilot.copilot_cli_short %} metrics fields](#copilot-cli-metrics-fields). |
 | `totals_by_copilot_app` | `object` | Yes | Aggregated daily metrics for the {% data variables.copilot.github_copilot_app_short %}. Null when the enterprise or organization has no activity in the {% data variables.copilot.github_copilot_app_short %} that day. See [Metrics fields for the {% data variables.copilot.github_copilot_app_short %}](#copilot-app-metrics-fields). |
 | `totals_by_3rd_party_agent` | `array` | Yes | Aggregated per-agent usage metrics for recognized {% data variables.copilot.agent_apps %}. Omitted when the enterprise or organization had no recognized {% data variables.copilot.agent_app %} activity that day. See [{% data variables.copilot.agent_apps_caps %} metrics fields](#agent-apps-metrics-fields). |
+| `totals_by_client` | `array` | No | Aggregated per-client breakdown of successful model requests and token usage for the day, counted server-side. The array is always present and is empty when there is no usage to report. In 28-day reports, this field appears within each `day_totals` entry. See [Client metrics fields](#client-metrics-fields). |
 | `totals_by_vscode_agent` | `object` | Yes | Aggregated dedicated {% data variables.product.prodname_vscode_shortname %} Agents-window metrics for the day. Omitted when both required counts are not available. See [{% data variables.product.prodname_vscode_shortname %} Agents-window metrics fields](#vs-code-agents-window-metrics-fields). |
 | `totals_by_ai_adoption_phase` | `array` | Yes | Per-phase aggregates of users and their average activity. Omitted when no adoption-phase data is available. See [AI adoption phase fields](#ai-adoption-phase-fields). |
 | `pull_requests` | `object` | No | Daily pull request activity for the enterprise or organization. See [Pull request activity fields](#pull-request-activity-fields). |
@@ -419,6 +421,34 @@ These metrics come from server-side job activity. The nested `user_initiated_int
 | `totals_by_3rd_party_agent[].user_initiated_interaction_count` | `integer` | No | Number of user-initiated jobs started for the {% data variables.copilot.agent_app %} during the reporting period. Each job start increments the count once. |
 | `totals_by_3rd_party_agent[].session_count` | `integer` | No | Sum of distinct, non-empty session counts for integrations mapped to the agent during the reporting period. Included only in aggregated enterprise and organization reports; omitted from per-user reports. |
 
+### Client metrics fields
+
+The `totals_by_client` array breaks down successful model requests that went through the {% data variables.product.prodname_copilot_short %} API by the client that sent them. These metrics are counted server-side, so they include tools that use {% data variables.product.prodname_copilot_short %} as a model provider even when those tools send no editor telemetry, such as OpenCode. Activity from these tools doesn't appear in `totals_by_ide`, which relies on editor telemetry.
+
+`totals_by_client` is different from `totals_by_3rd_party_agent`. The `totals_by_3rd_party_agent` array counts job starts for recognized {% data variables.copilot.agent_apps %} and doesn't include token or model data.
+
+Clients are identified from the integration ID that each client sends with its requests. Treat `client` as a best-effort grouping, not a verified identity.
+
+Within `totals_by_client`, the `request_count` fields count successful model calls, not prompts. A single prompt can trigger several model calls. Don't compare these request counts with prompt or interaction counts, such as `user_initiated_interaction_count` or `totals_by_cli.prompt_count`.
+
+The `totals_by_client` array appears at the top level of each record in per-user 1-day and 28-day reports and in aggregated 1-day reports. In aggregated 28-day reports, it appears within each `day_totals` entry. The array is always present and is empty when there is no usage to report.
+
+| Field | Type | Nullable | Description |
+|:--|:--|:--|:--|
+| `totals_by_client[].client` | `string` | No | Normalized client name. Known values include `vscode`, `visualstudio`, `jetbrains`, `eclipse`, `xcode`, `zed`, `copilot_cli`, `github_app`, `copilot_sdk`, `cloud_agent`, `code_review`, `github_web`, `github_mobile`, `github_desktop`, `agentic_workflows`, `claude_code`, `codex`, `opencode`, `slack`, and `azure_devops`. Requests with an unrecognized or missing integration ID are grouped as `other`. Values may be added over time. |
+| `totals_by_client[].request_count` | `integer` | No | Number of successful model requests from the client. Counts model calls, not prompts. |
+| `totals_by_client[].session_count` | `integer` | No | Number of distinct sessions for the client. In aggregated enterprise and organization reports, sessions are de-duplicated across all users, so this value isn't the sum of per-user counts. Unlike `totals_by_3rd_party_agent[].session_count`, this field is also included in per-user reports. |
+| `totals_by_client[].token_usage.prompt_tokens_sum` | `integer` | No | Total number of prompt tokens sent across the client's requests. |
+| `totals_by_client[].token_usage.output_tokens_sum` | `integer` | No | Total number of output tokens generated across the client's requests. |
+| `totals_by_client[].token_usage.avg_tokens_per_request` | `number` | No | Average number of **output** and **prompt** tokens per request, computed as `(output_tokens_sum + prompt_tokens_sum) ÷ request_count`. |
+| `totals_by_client[].totals_by_model` | `array` | No | Per-model breakdown of the client's requests and token usage. Entries are keyed on `model` and `model_selection_mode`, so the same model can appear more than once with different selection modes. |
+| `totals_by_client[].totals_by_model[].model` | `string` | No | Model used for the requests. For `code_review`, the model is always reported as `unknown`. |
+| `totals_by_client[].totals_by_model[].model_selection_mode` | `string` | No | How the model was selected. Possible values are `user_selected` (a specific model was requested rather than Auto), `product_selected` (the product chose the model, used for all {% data variables.copilot.copilot_code-review_short %} and {% data variables.copilot.copilot_cloud_agent %} requests), `auto` (Auto chose the model), `other` (selection modes that are grouped together and not yet reported individually), and `unknown` (a selection mode sent by the client that couldn't be normalized). |
+| `totals_by_client[].totals_by_model[].request_count` | `integer` | No | Number of successful model requests from the client that used this model and selection mode. |
+| `totals_by_client[].totals_by_model[].token_usage.prompt_tokens_sum` | `integer` | No | Total number of prompt tokens sent across these requests. |
+| `totals_by_client[].totals_by_model[].token_usage.output_tokens_sum` | `integer` | No | Total number of output tokens generated across these requests. |
+| `totals_by_client[].totals_by_model[].token_usage.avg_tokens_per_request` | `number` | No | Average number of **output** and **prompt** tokens per request, computed as `(output_tokens_sum + prompt_tokens_sum) ÷ request_count`. |
+
 ### Pull request activity fields
 
 > [!IMPORTANT]

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

@@ -52,6 +52,54 @@ The following examples show schemas for user-, enterprise-, and repository-level
       "prompt_tokens_sum": 3800
     }
   },
+  "totals_by_client": [{
+    "client": "opencode",
+    "request_count": 3,
+    "session_count": 2,
+    "token_usage": {
+      "avg_tokens_per_request": 1100.0,
+      "output_tokens_sum": 900,
+      "prompt_tokens_sum": 2400
+    },
+    "totals_by_model": [{
+      "model": "claude-opus-5.5",
+      "model_selection_mode": "user_selected",
+      "request_count": 2,
+      "token_usage": {
+        "avg_tokens_per_request": 1200.0,
+        "output_tokens_sum": 600,
+        "prompt_tokens_sum": 1800
+      }
+    }, {
+      "model": "claude-sonnet-5",
+      "model_selection_mode": "auto",
+      "request_count": 1,
+      "token_usage": {
+        "avg_tokens_per_request": 900.0,
+        "output_tokens_sum": 300,
+        "prompt_tokens_sum": 600
+      }
+    }]
+  }, {
+    "client": "copilot_cli",
+    "request_count": 1,
+    "session_count": 1,
+    "token_usage": {
+      "avg_tokens_per_request": 600.0,
+      "output_tokens_sum": 100,
+      "prompt_tokens_sum": 500
+    },
+    "totals_by_model": [{
+      "model": "gpt-5.6-sol",
+      "model_selection_mode": "user_selected",
+      "request_count": 1,
+      "token_usage": {
+        "avg_tokens_per_request": 600.0,
+        "output_tokens_sum": 100,
+        "prompt_tokens_sum": 500
+      }
+    }]
+  }],
   "totals_by_copilot_app": {
     "prompt_count": 1,
     "request_count": 3,
@@ -194,6 +242,8 @@ Customizations with unavailable names or names that look like file paths remain
 
 For coverage and naming rules, see [AUTOTITLE](/copilot/reference/copilot-usage-metrics/copilot-usage-metrics#customization-fields-api-only).
 
+The `totals_by_client` array appears at the top level of each user record in both 1-day and 28-day per-user reports, for both enterprise and organization scopes. It counts successful model requests server-side, so it can include clients, such as OpenCode, that don't appear in `totals_by_ide`.
+
 In this example, `used_copilot_code_review_active` and `used_copilot_code_review_passive` are `null` because there was no {% data variables.copilot.copilot_code-review_short %} signal for the user that day. `used_copilot_cloud_agent` and `used_copilot_coding_agent` always carry the same value.
 
 ## Enterprise-level schema example
@@ -300,6 +350,54 @@ In this example, `used_copilot_code_review_active` and `used_copilot_code_review
         "prompt_tokens_sum" : 5300
       }
     },
+    "totals_by_client" : [ {
+      "client" : "opencode",
+      "request_count" : 3,
+      "session_count" : 2,
+      "token_usage" : {
+        "avg_tokens_per_request" : 1100.0,
+        "output_tokens_sum" : 900,
+        "prompt_tokens_sum" : 2400
+      },
+      "totals_by_model" : [ {
+        "model" : "claude-opus-5.5",
+        "model_selection_mode" : "user_selected",
+        "request_count" : 2,
+        "token_usage" : {
+          "avg_tokens_per_request" : 1200.0,
+          "output_tokens_sum" : 600,
+          "prompt_tokens_sum" : 1800
+        }
+      }, {
+        "model" : "claude-sonnet-5",
+        "model_selection_mode" : "auto",
+        "request_count" : 1,
+        "token_usage" : {
+          "avg_tokens_per_request" : 900.0,
+          "output_tokens_sum" : 300,
+          "prompt_tokens_sum" : 600
+        }
+      } ]
+    }, {
+      "client" : "copilot_cli",
+      "request_count" : 1,
+      "session_count" : 1,
+      "token_usage" : {
+        "avg_tokens_per_request" : 600.0,
+        "output_tokens_sum" : 100,
+        "prompt_tokens_sum" : 500
+      },
+      "totals_by_model" : [ {
+        "model" : "gpt-5.6-sol",
+        "model_selection_mode" : "user_selected",
+        "request_count" : 1,
+        "token_usage" : {
+          "avg_tokens_per_request" : 600.0,
+          "output_tokens_sum" : 100,
+          "prompt_tokens_sum" : 500
+        }
+      } ]
+    } ],
     "totals_by_copilot_app" : {
       "prompt_count" : 2,
       "request_count" : 6,
@@ -501,6 +599,45 @@ In this example, `used_copilot_code_review_active` and `used_copilot_code_review
       "users_in_phase_28d" : 1,
       "total_pull_requests_merged" : 0
     } ],
+    "totals_by_client" : [ {
+      "client" : "github_app",
+      "request_count" : 2,
+      "session_count" : 1,
+      "token_usage" : {
+        "avg_tokens_per_request" : 1000.0,
+        "output_tokens_sum" : 500,
+        "prompt_tokens_sum" : 1500
+      },
+      "totals_by_model" : [ {
+        "model" : "gpt-5.6-sol",
+        "model_selection_mode" : "user_selected",
+        "request_count" : 2,
+        "token_usage" : {
+          "avg_tokens_per_request" : 1000.0,
+          "output_tokens_sum" : 500,
+          "prompt_tokens_sum" : 1500
+        }
+      } ]
+    }, {
+      "client" : "code_review",
+      "request_count" : 2,
+      "session_count" : 1,
+      "token_usage" : {
+        "avg_tokens_per_request" : 800.0,
+        "output_tokens_sum" : 400,
+        "prompt_tokens_sum" : 1200
+      },
+      "totals_by_model" : [ {
+        "model" : "unknown",
+        "model_selection_mode" : "product_selected",
+        "request_count" : 2,
+        "token_usage" : {
+          "avg_tokens_per_request" : 800.0,
+          "output_tokens_sum" : 400,
+          "prompt_tokens_sum" : 1200
+        }
+      } ]
+    } ],
     "totals_by_custom_agent" : [ ],
     "totals_by_feature" : [ {
       "code_acceptance_activity_count" : 1,
@@ -599,6 +736,8 @@ Organization aggregated reports use the same top-level `copilot_feature_engageme
 
 The customization fields shown in `day_totals` apply to enterprise and organization aggregated 28-day reports. They also appear directly in enterprise and organization aggregated 1-day reports. Like per-user reports, these aggregated reports include configured names for customizations created by your organization.
 
+Similarly, `totals_by_client` appears within each `day_totals` entry in enterprise and organization aggregated 28-day reports, and directly on the record in aggregated 1-day reports. In aggregated reports, each `totals_by_client` entry's `session_count` is de-duplicated across all users rather than summed from per-user counts.
+
 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]