Automating usage reporting with the REST API

You can automatically pull data from GitHub to populate the business systems you use to monitor costs and usage using the REST API. If you haven't used the GitHub REST API before, the following articles are a good starting point, see "Using the REST API.

Using the billing platform /usage endpoint to retrieve metered usage details for an enterprise

The enhanced billing platform provides a single REST API /usage endpoint that you can use to report on the use of all metered products. The usage data provided by this endpoint is available only to enterprise owners and enterprise billing managers, so you will need to authenticate with GitHub.

• If you use the GitHub CLI, use the gh auth login command to authenticate.
• Otherwise, you will need to create a personal access token (classic), see "Creating a personal access token (classic)."

When you call the /usage endpoint, you must specify the enterprise that you want data for and, by default, usage for the current year that does not belong to a cost center is reported. You can reduce the scope of data returned by the endpoint using query parameters.

• Define a specific time period by setting one or more of the following parameters: year, month, day, and hour.
• Define a cost center to report on by identifier using the cost_center_id query parameter.

For more detailed information and an example call and response, see Get billing usage report for an enterprise.

Migrating from the endpoints used for the previous billing platform

The previous billing platform provided three different endpoints for usage data:

• Get GitHub Actions billing for an enterprise
• Get GitHub Packages billing for an enterprise
• Get shared storage billing for an enterprise

When you transition to the enhanced billing platform, these endpoints will no longer return accurate usage information. You should upgrade any automation that uses these endpoints to use the new endpoint GET /enterprises/{enterprise}/settings/billing/usage. The tables below provide a detailed explanation how to use the billing platform to retrieve equivalent information.

Changes in call definition

If you used a fine-grained personal access token to authenticate with the previous endpoints, you will need create a personal access token (classic) to authenticate with the new endpoint.

In addition, you may want to use the new query parameters to specify a time period or cost center.

Getting GitHub Actions billing data from the new response data

Example of the previous response

{"total_minutes_used": 305, "total_paid_minutes_used": 0, "included_minutes": 3000, "minutes_used_breakdown": { "UBUNTU": 205, "MACOS": 10, "WINDOWS": 90 }  }

Example of the new response

{ "usageItems": [ { "date": "2023-08-01", "product": "Actions", "sku": "Actions Linux", "quantity": 100, "unitType": "minutes", "pricePerUnit": 0.008, "grossAmount": 0.8, "discountAmount": 0, "netAmount": 0.8, "organizationName": "GitHub", "repositoryName": "github/example"} ] }

To get the same values from the new response data:

Getting GitHub Packages billing data from the new response data

Example of the previous response

{ "total_gigabytes_bandwidth_used": 50, "total_paid_gigabytes_bandwidth_used": 40, "included_gigabytes_bandwidth": 10 }

Example of the new response

{ "usageItems": [ { "date": "2023-08-01", "product": "Packages", "sku": "Packages data transfer", "quantity": 100, "unitType": "gigabytes", "pricePerUnit": 0.008, "grossAmount": 0.8, "discountAmount": 0, "netAmount": 0.8, "organizationName": "GitHub", "repositoryName": "github/example" } ] }

Getting shared storage billing from the new response data

Example of the previous response

{ "days_left_in_billing_cycle": 20, "estimated_paid_storage_for_month": 15, "estimated_storage_for_month": 40 }

Example of the new response

{ "usageItems": [ { "date": "2023-08-01", "product": "Packages", "sku": "Packages storage", "quantity": 100, "unitType": "GigabyteHours", "pricePerUnit": 0.008, "grossAmount": 0.8, "discountAmount": 0, "netAmount": 0.8, "organizationName": "GitHub", "repositoryName": "github/example" } ] }