{"meta":{"title":"Usage reports","intro":"Use the REST API to create and retrieve usage report exports for an enterprise.","product":"REST API","breadcrumbs":[{"href":"/en/enterprise-cloud@latest/rest","title":"REST API"},{"href":"/en/enterprise-cloud@latest/rest/billing","title":"Billing"},{"href":"/en/enterprise-cloud@latest/rest/billing/usage-reports","title":"Usage reports"}],"documentType":"article"},"body":"# Usage reports\n\nUse the REST API to create and retrieve usage report exports for an enterprise.\n\n> [!NOTE]\n> Most endpoints use `Authorization: Bearer <YOUR-TOKEN>` and `Accept: application/vnd.github+json` headers, plus `X-GitHub-Api-Version: 2026-03-10`. Curl examples below omit these standard headers for brevity.\n\n## List usage report exports\n\n```\nGET /enterprises/{enterprise}/settings/billing/reports\n```\n\nLists all usage report exports for an enterprise. 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 list usage report exports.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`enterprise`** (string) (required)\n  The slug version of the enterprise name.\n\n### HTTP response status codes\n\n- **200** - List of usage report exports\n\n- **401** - Requires authentication\n\n- **403** - Forbidden\n\n- **404** - Resource not found\n\n- **500** - Internal Error\n\n- **503** - Service unavailable\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/enterprises/ENTERPRISE/settings/billing/reports\n```\n\n**Response schema (Status: 200):**\n\n* `usage_report_exports`: required, array of objects:\n  * `id`: required, string, format: uuid\n  * `report_type`: required, string, enum: `detailed`, `summarized`, `premium_request`, `ai_credit`\n  * `start_date`: required, string, format: date\n  * `end_date`: required, string, format: date\n  * `status`: required, string, enum: `processing`, `completed`, `failed`\n  * `download_urls`: array of string\n  * `created_at`: string, format: date-time\n  * `actor`: string\n\n## Create a usage report export\n\n```\nPOST /enterprises/{enterprise}/settings/billing/reports\n```\n\nInitiates the generation of a usage report export for an enterprise. The report will be processed asynchronously\nand 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.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`enterprise`** (string) (required)\n  The slug version of the enterprise name.\n\n#### Body parameters\n\n- **`report_type`** (string) (required)\n  The type of usage report to generate\n  Can be one of: `detailed`, `summarized`, `premium_request`, `ai_credit`\n\n- **`start_date`** (string) (required)\n  The start date for the report in YYYY-MM-DD format\n\n- **`end_date`** (string)\n  The end date for the report in YYYY-MM-DD format. Defaults to today (UTC) if not provided.\n\n- **`send_email`** (boolean)\n  Whether to send an email notification to the requester when the report is ready. Defaults to false.\n  Default: `false`\n\n### HTTP response status codes\n\n- **202** - Report export request accepted\n\n- **400** - Bad Request\n\n- **401** - Requires authentication\n\n- **403** - Forbidden\n\n- **404** - Resource not found\n\n- **500** - Internal Error\n\n- **503** - Service unavailable\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X POST \\\n  https://api.github.com/enterprises/ENTERPRISE/settings/billing/reports \\\n  -d '{\n  \"report_type\": \"detailed\",\n  \"start_date\": \"2024-01-01\",\n  \"end_date\": \"2024-01-31\"\n}'\n```\n\n**Response schema (Status: 202):**\n\n* `id`: required, string, format: uuid\n* `report_type`: required, string, enum: `detailed`, `summarized`, `premium_request`, `ai_credit`\n* `start_date`: required, string, format: date\n* `end_date`: required, string, format: date\n* `status`: required, string, enum: `processing`, `completed`, `failed`\n* `download_urls`: array of string\n* `created_at`: string, format: date-time\n* `actor`: string\n\n## Get a usage report export\n\n```\nGET /enterprises/{enterprise}/settings/billing/reports/{report_id}\n```\n\nGets the status and details of a usage report export by ID. 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 get a usage report export.\n\n### Parameters\n\n#### Headers\n\n- **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n- **`enterprise`** (string) (required)\n  The slug version of the enterprise name.\n\n- **`report_id`** (string) (required)\n  The unique identifier (UUID) for the usage report export.\n\n### HTTP response status codes\n\n- **200** - Usage report export details\n\n- **401** - Requires authentication\n\n- **403** - Forbidden\n\n- **404** - Resource not found\n\n- **500** - Internal Error\n\n- **503** - Service unavailable\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/enterprises/ENTERPRISE/settings/billing/reports/REPORT_ID\n```\n\n**Response schema (Status: 200):**\n\nSame response schema as [Create a usage report export](#create-a-usage-report-export)."}