Public preview of API for .CSV usage reports

[gmondello]

Note

This feature graduated from private to public preview on February 17, 2026 (changelog).

Overview

Enterprises can now programmatically request and download billing usage report CSVs via the REST API, eliminating the need to request usage reports in the UI and receive them via email. The API is currently available in private preview by request.

Prerequisites

1. Permissions: You must be an enterprise admin or billing manager.
2. PAT Scope: Generate a Personal Access Token with manage_billing:enterprise scope

Summary

The following report types are available via the API: Report types

Report Type	Max Date Range	Description
detailed	31 days	Detailed usage report for all paid products
summarized	366 days	Summary of usage for all paid products
premium_request	31 days	Detailed per-user breakdown of premium requests consumed

Endpoints

1. Request a report (POST)

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"

Request Parameters:

Parameter	Type	Required	Description
report_type	string	Yes	One of detailed, summarized, or premium_request
start_date	string	Yes	Start date in YYYY-MM-DD format
end_date	string	No	End date in YYYY-MM-DD format; defaults to today (UTC) if omitted
send_email	boolean	No	Whether to send an email notification when the report is ready. Defaults to false (no email sent). Set to true to receive an email with download links when the report completes.

Response (202 Accepted):

{
  "id": "834264f8-a124-435c-a791-051752537399",
  "report_type": "summarized",
  "status": "processing",
  "download_urls": [],
  ...
}

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

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"

Response when complete:

{
  "id": "834264f8-a124-435c-a791-051752537399",
  "status": "completed",
  "download_urls": [
    "https://mbproduction.blob.core.windows.net/billing-metered-exports-reports/...csv?sp=r&st=...&sig=..."
  ],
  ...
}

Polling: Average report generation time is 3 minutes. Poll every 30 seconds until status changes from "processing" to "completed".

3. Download the CSV

Once you have the URL, download directly:

curl -s "DOWNLOAD_URL" > report.csv

List All Reports (GET list)

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

Note: This endpoint intentionally does not include download_urls. You must fetch individual reports to get download links.

---

GitHub Enterprise Billing Report Download Script

#!/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
RESPONSE=$(curl -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

---

Known Issues

• "download_urls": [] is included in the response even when blank; this will be removed in a future update.

---

Requesting access and providing feedback

Please report any issues, unexpected behavior, or suggestions below!

[github-actions[bot]]

💬 Your Product Feedback Has Been Submitted 🎉

Thank you for taking the time to share your insights with us! Your feedback is invaluable as we build a better GitHub experience for all our users.

Here's what you can expect moving forward ⏩

• Your input will be carefully reviewed and cataloged by members of our product teams. 
  • Due to the high volume of submissions, we may not always be able to provide individual responses.
  • Rest assured, your feedback will help chart our course for product improvements.
• Other users may engage with your post, sharing their own perspectives or experiences. 
• GitHub staff may reach out for further clarification or insight. 
  • We may 'Answer' your discussion if there is a current solution, workaround, or roadmap/changelog post related to the feedback.

Where to look to see what's shipping 👀

• Read the Changelog for real-time updates on the latest GitHub features, enhancements, and calls for feedback.
• Explore our Product Roadmap, which details upcoming major releases and initiatives.

What you can do in the meantime 💻

• Upvote and comment on other user feedback Discussions that resonate with you.
• Add more information at any point! Useful details include: use cases, relevant labels, desired outcomes, and any accompanying screenshots.

As a member of the GitHub community, your participation is essential. While we can't promise that every suggestion will be implemented, we want to emphasize that your feedback is instrumental in guiding our decisions and priorities.

Thank you once again for your contribution to making GitHub even better! We're grateful for your ongoing support and collaboration in shaping the future of our platform. ⭐