Automating GitHub Enterprise Billing: A Strategic Move for Engineering Performance Metrics

Streamlining Enterprise Billing with GitHub's New Usage Reports API

For large organizations managing extensive GitHub Enterprise deployments, the task of tracking and analyzing billing usage has traditionally involved manual processes, often relying on UI requests and email deliveries. This approach, while functional, can be a bottleneck for timely data analysis and proactive cost management. GitHub is addressing this challenge head-on with the private preview of a new REST API, designed for programmatic access to .CSV usage reports.

This significant enhancement allows enterprises to automate the retrieval of critical billing data, moving away from the cumbersome manual requests. By integrating directly with the API, organizations can build custom dashboards, trigger automated alerts, and gain deeper insights into their resource consumption, directly impacting their ability to monitor and improve engineering performance metrics related to cost efficiency and resource allocation.

Key Features and Prerequisites

The new API empowers enterprise administrators and billing managers with unprecedented control over their billing data. To leverage this functionality, a few prerequisites must be met:

• The API must be activated by GitHub for your enterprise.
• Users require enterprise admin or billing manager permissions.
• A Personal Access Token (PAT) with the manage_billing:enterprise scope is essential for authentication.

The API offers three distinct report types, each serving different analytical needs:

• detailed: Provides a detailed usage report for all paid products, covering a maximum date range of 31 days.
• summarized: Offers a summary of usage for all paid products, with an extended maximum date range of 366 days.
• premium_request: Delivers a detailed per-user breakdown of premium requests consumed, also with a 31-day maximum range.

Programmatic Access to Your Billing Data

The API workflow is straightforward, involving a few key endpoints:

1. Request a Report (POST)

Initiate the report generation process by sending a POST request. You specify the report type, start and end dates, and whether an email notification is desired upon completion.

curl -X POST \
 -H "Authorization: Bearer $TOKEN" \
 -H "Accept: application/vnd.github+json" \
 -H "Content-Type: application/json" \
 -d '{ "report_type": "summarized", "start_date": "2025-12-01", "end_date": "2025-12-31", "send_email": true }' \
 "https://api.github.com/enterprises/YOUR_ENTERPRISE/settings/billing/reports"

2. Get Report Status & Download URL (GET single)

Reports are generated asynchronously. After requesting a report, you'll receive an id. You can then poll this endpoint using the report ID to check its status. Once the status changes to "completed", the response will include the secure download URLs for your CSV file.

curl -X GET \
 -H "Authorization: Bearer $TOKEN" \
 -H "Accept: application/vnd.github+json" \
 "https://api.github.com/enterprises/YOUR_ENTERPRISE/settings/billing/reports/REPORT_ID"

3. Download the CSV

With the download URL in hand, a simple curl command can retrieve the .CSV file directly.

curl -s "DOWNLOAD_URL" > report.csv

Example: Automating Report Downloads

To illustrate the power of this API, GitHub provided a practical bash script. This script demonstrates how to request a summarized billing report, poll its status until completion, and then download the resulting CSV file. This kind of automation is crucial for teams focused on improving software developer efficiency by removing manual administrative tasks.

#!/bin/bash
# Example download script
# This script creates a summarized billing report and downloads it as a CSV file
# Not intended for production use - use environment variables or GitHub CLI for auth

export TOKEN="your-pat-here"
export ENTERPRISE="your-enterprise-slug"

# Create report
# - report_type: "summarized", "detailed", "premium_request"
# - start_date/end_date: YYYY-MM-DD format
# - Optional: add "send_email": true to receive email notification when complete
RESP -s -X POST \
 -H "Authorization: Bearer $TOKEN" \
 -H "Accept: application/vnd.github+json" \
 -H "Content-Type: application/json" \
 -d '{"report_type": "summarized", "start_date": "2026-01-01", "end_date": "2026-01-31"}' \
 "https://api.github.com/enterprises/$ENTERPRISE/settings/billing/reports")

REPORT_ID=$(echo $RESPONSE | jq -r '.id')
echo "Created report: $REPORT_ID"

# Poll until complete
for i in $(seq 1 60); do
 RESULT=$(curl -s -X GET \
 -H "Authorization: Bearer $TOKEN" \
 -H "Accept: application/vnd.github+json" \
 "https://api.github.com/enterprises/$ENTERPRISE/settings/billing/reports/$REPORT_ID")
 STATUS=$(echo "$RESULT" | jq -r '.status')
 echo "[$i] status=$STATUS"
 if [ "$STATUS" = "completed" ]; then
 DOWNLOAD_URL=$(echo "$RESULT" | jq -r '.download_urls[0]')
 echo "Downloading report..."
 curl -s -o "billing_report_${ENTERPRISE}.csv" "$DOWNLOAD_URL"
 echo "Saved to billing_report_${ENTERPRISE}.csv"
 break
 fi
 sleep 30
done

Looking Ahead

While still in private preview, this API marks a significant step towards more robust enterprise management on GitHub. The ability to programmatically access billing data opens doors for advanced analytics, cost optimization strategies, and better-informed decisions regarding resource allocation, all contributing to a more efficient development ecosystem and sharper engineering performance metrics. GitHub encourages users to request access and provide feedback to help shape the future of this valuable tool.