Seeking Schema/Sample JSONs for Copilot Usage Metrics Exports: Documentation Gap on Data Hierarchy

[onur-verdo]

Select Topic Area

Question

Copilot Feature Area

General

Body

Hi everyone,

I am currently analyzing the GitHub Copilot Usage Metrics API (version 2022-11-28) to assess data quality and attribution depth.

Since this API provides download links to JSON files instead of direct responses, there is a lack of documentation regarding the actual data hierarchy within these exports. While the 'exported keys' are listed in the documentation, the nesting logic and specific data types (especially for breakdowns like IDEs, features, or models) are not transparent.

My questions:

1. Does anyone have a Sample/Dummy JSON of these export files (e.g., for the enterprise, organization, or user level reports)?
2. Beyond the official docs, is there any way to validate the JSON schema or simulate the data retrieval (e.g., via Mock APIs, Postman collections, or OpenAPI specs) without having a live Enterprise account?

If no mocks or samples are available, I’d like to understand the practical path to success for this analysis:

• Is it possible to access these specific JSON exports through a standard Copilot Business subscription, or is a full GitHub Enterprise account strictly required?
• Are there any developer programs or lower-tier evaluation licenses that grant access to these Copilot Usage Metrics API features?

I am trying to understand the granularity and internal structure of the data before moving into technical implementation. Any shared samples, community-maintained mocks, or technical insights would be greatly appreciated.

Best regards,
Onur

[kovalllllll]

Hi Onur,

This is a common pain point. Because the Copilot Usage Metrics API follows an asynchronous pattern (requesting the endpoint returns a 200 with the raw data, or occasionally a download link depending on the API version and volume), the schema is often opaque until you actually have data flowing.

Here is the breakdown of the JSON structure, the schema validation options, and the subscription requirements you asked for.

1. Sample JSON Structure (Usage Metrics)

The data is typically returned as an Array of Objects, where each object represents a single day of aggregated metrics.

Here is a high-fidelity dummy sample of what the Organization and Enterprise usage metrics JSON looks like. Note the nesting of the breakdown field, which contains the specific language/editor combinations.

code
JSON
download
content_copy
expand_less
[
{
"day": "2023-10-24",
"total_suggestions_count": 2500,
"total_acceptances_count": 750,
"total_lines_suggested": 10500,
"total_lines_accepted": 3200,
"total_active_users": 15,
"total_chat_acceptances": 40,
"total_chat_turns": 120,
"total_active_chat_users": 5,
"breakdown": [
{
"language": "python",
"editor": "vscode",
"suggestions_count": 1500,
"acceptances_count": 500,
"lines_suggested": 6000,
"lines_accepted": 2000,
"active_users": 10
},
{
"language": "javascript",
"editor": "jetbrains",
"suggestions_count": 1000,
"acceptances_count": 250,
"lines_suggested": 4500,
"lines_accepted": 1200,
"active_users": 5
}
]
},
{
"day": "2023-10-25",
"total_suggestions_count": 2800,
"total_acceptances_count": 900,
"total_lines_suggested": 12000,
"total_lines_accepted": 4000,
"total_active_users": 18,
"total_chat_acceptances": 55,
"total_chat_turns": 150,
"total_active_chat_users": 8,
"breakdown": [
{
"language": "go",
"editor": "vscode",
"suggestions_count": 2800,
"acceptances_count": 900,
"lines_suggested": 12000,
"lines_accepted": 4000,
"active_users": 18
}
]
}
]

Key Data nuances:

Privacy Aggregation: If the count for a specific breakdown (e.g., "Ruby in Vim") is too low, GitHub may exclude it or group it to protect user privacy, though this usually happens at the user-attribution level rather than the org-wide aggregate level.

API Versioning: The 2022-11-28 version is the standard REST API version, but the specific fields (like chat_turns) were added incrementally. Ensure your parser handles optional fields/nulls.

2. Validation and Simulation

Since there is no "Sandbox" or "Mock Server" provided by GitHub for this specific payload:

OpenAPI Spec: GitHub publishes their OpenAPI descriptions in the github/rest-api-description repository. However, for the Copilot Usage endpoint, the spec often describes the response structure loosely. It does not strictly define every possible permutation of the breakdown object in a way that generates a perfect mock automatically.

Recommendation: Use the JSON sample above to generate a JSON Schema (using a tool like quicktype.io or an online JSON-to-Schema converter). You can then use this schema to validate your ingestion pipeline without needing a live API connection.

3. Subscription & Access Requirements

To answer your path to success:

Q: Is a full GitHub Enterprise account strictly required?
A: No, but you need at least an Organization with Copilot Business.

There are two levels of the API:

Organization Usage: GET /orgs/{org}/copilot/usage

Requires: GitHub Copilot Business (GCB) subscription.

Access: Organization Owners.

This gives you the metrics for that specific organization.

Enterprise Usage: GET /enterprises/{enterprise}/copilot/usage

Requires: GitHub Copilot Enterprise (or GCB rolled up to an Enterprise account).

Access: Enterprise Owners.

Q: Are there developer programs/eval licenses?
A: Not for the API specifically.
GitHub does not offer a free "developer tier" for Copilot Business/Enterprise APIs.

The Practical Path to Success (Lowest Cost):

Create a GitHub Organization (Free tier for the Org itself).

Enable Copilot Business for that Organization.

This is priced at $19/user/month.

Add one user (yourself) to the Copilot seat list.

Wait 24-48 hours. The usage metrics pipeline is not real-time; it is a daily batch process. You need to generate some activity (code in VS Code, use Chat) to populate the data.

Call the API: You can now query /orgs/{your-org}/copilot/usage to get the real JSON export.

This approach allows you to build and test your implementation for roughly $19 (one month of one seat), rather than requiring a full Enterprise contract.

Summary of Keys for Parsing

When building your parser, ensure you account for:

total_suggestions_count vs total_acceptances_count (The Acceptance Rate calculation).

breakdown is an array that mixes language and editor.

Fields like total_chat_turns are newer and may appear as 0 or null in older data ranges if you request historical data.

Hope this helps you move forward with your implementation!

[onur-verdo]

Hi,

thank you for the answer. I am a bit confused because the API endpoint you mentioned and the JSON structure you provided seem to come from two different places. I want to make sure I don't build my integration based on a misunderstanding.

My main question is:
If I use the Usage Metrics API (the one that provides download_links), will the file behind that link (e.g. copilot-usage-report-1.json) look exactly like the JSON you posted?

Usage Metrics API (download_links)

{
  "download_links": [
    "https://example.com/copilot-usage-report-1.json",
    "https://example.com/copilot-usage-report-2.json"
  ],
  "report_start_day": "2025-07-01",
  "report_end_day": "2025-07-28"
}

The JSON you posted (abbreviated)

[
  {
    "day": "2023-10-24",
    "total_suggestions_count": 2500,
    "total_acceptances_count": 750,
    "breakdown": [
      { "language": "python", "editor": "vscode", "suggestions_count": 1500 }
    ]
  }
]

Why I am asking for clarification: I suspect there might be a mix-up regarding which API delivers which format:

The structure you posted is identical to what I've seen in this YouTube video at 0:45. That video refers to an endpoint like */copilot/usage, which is also the JSON schema you suggested here, but I cannot find it in the current official documentation.

However, the official Usage Metrics / Reports API documentation (which is the one I am actually trying to use) refers to a field reference that lists completely different, more granular fields like loc_suggested_to_add_sum instead of a simple total_suggestions_count.

[m3ac-AllbrittenJ]

Adding to this, the documented https://docs.github.com/en/copilot/reference/copilot-usage-metrics/copilot-usage-metrics is missing large portions of the schema returned in the user level usage data reports

In fact, I can find zero dedicated documentation or descriptions of all the fields returned anywhere.

This has become a major issue as we attempt to integrate the APIs into our processes

[onur-verdo]

https://docs.github.com/en/enterprise-cloud@latest/copilot/reference/copilot-usage-metrics/example-schema