billing

Create a usage report export

Changed on

Initiates the generation of a usage report export for an enterprise. The report will be processed asynchronously and can be downloaded once completed. The authenticated user must be an enterprise admin or billing manager, or a custom role holder with fine-grained read access to enterprise billing. An installation access token for a GitHub App installed on the enterprise with write access to enterprise administration, or with read access to enterprise billing, can also initiate a usage report export.

[!NOTE] The "Enterprise administration" fine-grained permission is not available to callers. To use this API, you must use an OAuth app token or a personal access token (classic), or another supported fine-grained permission.

post/enterprises/{enterprise}/settings/billing/reports

Request

  • Base URL: https://api.github.com
  • URL: https://api.github.com/enterprises/{enterprise}/settings/billing/reports
  • Auth: none declared

Path parameters

enterprisestring required

The slug version of the enterprise name.

Request body

report_type'detailed' | 'summarized' | 'premium_request' | 'ai_credit' required

The type of usage report to generate

start_datestring date required

The start date for the report in YYYY-MM-DD format

end_datestring date

The end date for the report in YYYY-MM-DD format. Defaults to today (UTC) if not provided.

send_emailboolean

Whether to send an email notification to the requester when the report is ready. Defaults to false.

Example request

{
  "start_date": "2024-01-01",
  "end_date": "2024-01-31"
}

Response

Report export request accepted

idstring uuid required

Unique identifier for the usage report export

report_type'detailed' | 'summarized' | 'premium_request' | 'ai_credit' required

The type of usage report

start_datestring date required

The start date for the report

end_datestring date required

The end date for the report

status'processing' | 'completed' | 'failed' required

The current status of the report export

download_urlsstring[]

URLs to download the completed report. Only present when the report status is completed.

created_atstring date-time

When the report export was created

actorstring

The login of the user who requested the export

Example response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "report_type": "detailed",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "status": "completed",
  "download_urls": [
    "https://github.com/enterprises/github/metered_exports/1234"
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "actor": "monalisa"
}

Changes

  • 2022-11-28783af1c7188bRevision changes
    • warning

      added the new ai_credit enum value to the response property for the response status

    • info

      added the new ai_credit enum value to the request property