{"meta":{"title":"Automating usage reporting with the REST API","intro":"Learn how to automate reporting on your use of paid features using the REST API.","product":"Billing and payments","breadcrumbs":[{"href":"/en/billing","title":"Billing and payments"},{"href":"/en/billing/tutorials","title":"Tutorials"},{"href":"/en/billing/tutorials/automate-usage-reporting","title":"Automate usage reporting"}],"documentType":"article"},"body":"# Automating usage reporting with the REST API\n\nLearn how to automate reporting on your use of paid features using the REST API.\n\nAfter 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.\n\nIn 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.\n\n## Prerequisites\n\nBefore you begin this tutorial, make sure that:\n\n* You have access to billing data at the level you want to report on:\n  * User-level reports: account holder\n  * Organization-level reports: organization owner or billing manager\n  * Enterprise-level reports: enterprise administrator or billing manager\n\n* You’re familiar with making authenticated requests to the REST API. For an introduction, see [Using the REST API](/en/rest/using-the-rest-api).\n\n* You authenticate using a personal access token (classic). The billing usage endpoints do not support fine-grained personal access tokens.\n\nDepending 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.\n\n## Step 1: Decide what level to report on\n\nDecide which account level you want to report on. This determines **which REST API endpoint you’ll call** and what your report will include.\n\nChoose the reporting level that best matches your goal:\n\n| Reporting level  | When to use it                                                                                                         |\n| ---------------- | ---------------------------------------------------------------------------------------------------------------------- |\n| **User**         | You want a report for a single account, for example to understand personal usage and costs.                            |\n| **Organization** | You want to track usage and costs for a specific organization, for example for team-level monitoring or chargeback.    |\n| **Enterprise**   | You want a centralized view across multiple organizations, for example for finance reporting or cost center reporting. |\n\nOnce 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.\n\n## Step 2: Retrieve usage data for paid products\n\nAfter 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](/en/rest/billing/usage).\n\nGitHub provides two types of billing usage data:\n\n* **Usage summaries** – aggregated usage and cost data for all paid products.\n* **AI credits usage** – detailed usage and billing data for AI credits, including included pool consumption and additional usage spend.\n\nIn 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.\n\n### Retrieve a usage summary\n\nUse the usage summary endpoint that corresponds to the reporting level you chose in Step 1.\n\nFor example, to retrieve a usage summary for an enterprise, make a request to:\n\n`/enterprises/{enterprise}/settings/billing/usage/summary`\n\nYou must authenticate your request to this endpoint.\n\n**Example using curl**\n\n```bash\ncurl -L \\\n  -H \"Authorization: Bearer $GITHUB_TOKEN\" \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  https://api.github.com/enterprises/ENTERPRISE/settings/billing/usage/summary\n```\n\nReplace `ENTERPRISE` with the enterprise slug and set the `GITHUB_TOKEN` environment variable to a personal access token with the required billing permissions.\n\n**Example using the GitHub CLI**\n\n```bash\ngh api \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  /enterprises/ENTERPRISE/settings/billing/usage/summary\n```\n\nThis 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.\n\nYou can use the same approach to retrieve usage summaries for an organization or user by calling the equivalent endpoint for that account level.\n\n### Retrieve AI credits usage\n\nIf you need to report specifically on Copilot consumption, use the AI usage endpoint for the same account level. This endpoint provides additional details such as included pool usage, billed additional usage, and consumption by model.\n\n## Step 3: Filter usage data by time period or cost center\n\nBy default, usage summary endpoints return data for the **current year**. To generate more targeted reports or analyze trends over time, you can filter usage data using query parameters.\n\n### Filter by time period\n\nYou can limit the usage data returned by specifying one or more of the following query parameters:\n\n* `year`\n* `month`\n* `day`\n* `hour`\n\nFor example, to retrieve usage data for a specific month, include the `year` and `month` parameters in your request:\n\n```http\nGET /enterprises/{enterprise}/settings/billing/usage/summary?year=2024&month=12\n```\n\nFiltering by time period is useful when you want to:\n\n* Generate monthly or daily usage reports\n* Compare usage before and after a change, such as enabling a new feature\n* Reconcile usage with invoices for a specific billing period\n\n### Filter by cost center (enterprise only)\n\nIf you’re retrieving enterprise-level usage data, you can also filter results by cost center using the `cost_center_id` query parameter.\n\nFiltering by cost center allows you to:\n\n* Attribute usage and costs to specific teams or business units\n* Generate cost center–specific reports for finance or leadership stakeholders\n\nCost center filtering is available only for enterprise usage summary endpoints.\n\nIn the next step, you’ll learn how to automate these API calls to generate recurring usage reports.\n\n## Step 4: Automate recurring usage reports\n\nOnce you’ve identified the usage data you want to collect and how to filter it, you can automate your reporting by running the same API requests on a recurring schedule.\n\nCommon automation patterns include:\n\n* Running scheduled API requests (for example, daily or monthly) to collect usage data\n* Storing the results in an internal system such as a database, spreadsheet, or BI tool\n* Using the data to monitor trends, detect changes in usage, or support cost reviews\n\nWhen automating reports, consistency matters. Use the same reporting level, filters, and time ranges each time so that usage trends are comparable over time.\n\nFor example, you might:\n\n* Run a monthly enterprise-level usage summary to track overall spend\n* Generate cost center–specific reports for internal chargeback or showback\n* Monitor usage growth after enabling new paid features\n\nIn the next step, you’ll learn how to interpret the usage and cost fields returned by the API so you can turn raw data into meaningful insights.\n\n## Step 5: Interpret usage and cost fields in the API response\n\nThe usage summary response includes both **usage** and **cost** information. Understanding how these fields relate to each other helps you interpret spend, included usage, and billed overages.\n\nEach usage item includes:\n\n* A **quantity**, which represents the amount of usage for a specific product and unit type\n* A **netAmount**, which represents the billed cost for that usage\n* A **discountAmount**, which represents usage covered by included quotas or discounts\n\nIn general:\n\n* Use **quantity** to understand how much of a product was consumed\n* Use **netAmount** to understand what was billed\n* Use **discountAmount** to understand how much usage was included or discounted\n\nFor example, a high quantity with a low netAmount may indicate that most usage was covered by included quotas, while a rising netAmount over time may indicate increased paid usage.\n\nDifferent products report usage using different unit types (such as minutes, gigabytes, or requests). To calculate product-specific metrics or reproduce values from the previous billing platform, you may need to filter usage items by product and unit type and aggregate the results. Detailed examples are available in the reference documentation linked in the next step.\n\n## Step 6: Calculate product-specific usage metrics\n\nIn some cases, you may need to calculate product-specific usage metrics from the usage summary response. This is most relevant if you want to generate custom reports for a specific product or reproduce values used in legacy reporting.\n\nTo calculate these metrics, you typically filter usage items by `product` and `unitType`, then aggregate fields such as `quantity`, `netAmount`, and `discountAmount`.\n\nFor detailed examples and product-specific calculations, see [Introduction to billing and licensing](/en/billing/get-started/introduction-to-billing)."}