Automating usage reporting with the REST API

After you transition to metered billing, you may want to automatically track usage and costs for paid GitHub features in your internal reporting systems. For example, you might want to monitor spend over time, reconcile invoices, or feed usage data into finance or BI tools.

In this tutorial, you’ll learn how to use the REST API to retrieve billing usage data, filter it by time period or cost center, and automate recurring reports at the user, organization, or enterprise level. You’ll also learn how to interpret key fields in the response so you can turn raw usage data into meaningful cost insights.

Prerequisites

Before you begin this tutorial, make sure that:

• You have access to billing data at the level you want to report on:

  • User-level reports: account holder
  • Organization-level reports: organization owner or billing manager
  • Enterprise-level reports: enterprise administrator or billing manager

• You’re familiar with making authenticated requests to the REST API. For an introduction, see Using the REST API.

• You authenticate using a personal access token (classic). The billing usage endpoints do not support fine-grained personal access tokens. For enterprise-level reporting, you can authenticate with a GitHub App instead. See Authenticating with a GitHub App.

Depending on your reporting needs, you may also want access to an internal system (such as a spreadsheet, database, or BI tool) where you can store and analyze the usage data retrieved from the API.

Authenticating with a GitHub App

For enterprise-level reporting, you can authenticate with a GitHub App instead of a personal access token. Your automation then does not depend on a token that belongs to an individual enterprise owner or billing manager, so your reports keep running when someone changes role or leaves the enterprise.

An enterprise owner can grant an app the enterprise billing permission at one of two levels of access:

• Read: The app can retrieve usage reports, budgets, and cost centers. This is the access the reporting in this tutorial requires.
• Read and write: The app can create, update, and delete budgets and cost centers, and add or remove resources from cost centers.

To report on usage with an app:

1. Register a GitHub App that requests the enterprise billing permission. See Registering a GitHub App.
2. Ask an enterprise owner to install the app on your enterprise. See Installing a GitHub App on your enterprise.
3. Generate an installation access token for the enterprise installation. See Generating an installation access token for a GitHub App.
4. Send the installation access token in the Authorization header of your requests, in place of a personal access token.

An installation access token expires after one hour, so your automation must generate a new token each time it runs or whenever the current token expires.

For the endpoints an app can call with each permission, see Permissions required for GitHub Apps.

Step 1: Decide what level to report on

Decide which account level you want to report on. This determines which REST API endpoint you’ll call and what your report will include.

Choose the reporting level that best matches your goal:

Reporting level	When to use it
User	You want a report for a single account, for example to understand personal usage and costs.
Organization	You want to track usage and costs for a specific organization, for example for team-level monitoring or chargeback.
Enterprise	You want a centralized view across multiple organizations, for example for finance reporting or cost center reporting.

Once you’ve chosen a reporting level, you’ll use the corresponding endpoint in the next step to retrieve usage data and build an automated report.

Step 2: Retrieve usage data for paid products

After you’ve decided which level to report on, use the REST API to retrieve usage data for paid GitHub products. For all endpoints, see Billing usage.

GitHub provides two types of billing usage data:

• Usage summaries – aggregated usage and cost data for all paid products.
• AI credits usage – detailed usage and billing data for AI credits, including included pool consumption and additional usage spend.

In most reporting scenarios, you'll start with a usage summary to understand overall usage and spend, and then use AI credits usage data when you need deeper insight into Copilot consumption.

Retrieve a usage summary

Use the usage summary endpoint that corresponds to the reporting level you chose in Step 1.

For example, to retrieve a usage summary for an enterprise, make a request to:

/enterprises/{enterprise}/settings/billing/usage/summary

You must authenticate your request to this endpoint.

Example using curl

curl -L \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/settings/billing/usage/summary

Replace ENTERPRISE with the enterprise slug and set the GITHUB_TOKEN environment variable to a personal access token with the required billing permissions. Alternatively, set GITHUB_TOKEN to an installation access token from a GitHub App with the enterprise billing permission.

Example using the GitHub CLI

gh api \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /enterprises/ENTERPRISE/settings/billing/usage/summary

This endpoint returns aggregated usage data for all paid products for the current year by default. Each entry includes information such as the product, unit type, quantity used, and billed amount.