{"meta":{"title":"Budgets","intro":"使用 REST API 获取预算信息。","product":"REST API","breadcrumbs":[{"href":"/zh/enterprise-cloud@latest/rest","title":"REST API"},{"href":"/zh/enterprise-cloud@latest/rest/billing","title":"计费"},{"href":"/zh/enterprise-cloud@latest/rest/billing/budgets","title":"Budgets"}],"documentType":"article"},"body":"# Budgets\n\n使用 REST API 获取预算信息。\n\n> [!IMPORTANT]\n> 下面的请求正文架构缺少必填字段。 当 `budget_scope` 为 `user` 时，还必须包含一个 `user` 字段，并将其设置为该预算适用的 GitHub 用户名。 如果省略此字段，API 将 `HTTP 400: Missing required fields: budget_entity_name`返回 。 对于用户作用域预算，`budget_entity_name` 可以为空字符串。\n\n以下示例创建一个用户范围的预算，该预算将单个用户的每月 CopilotAI credits 限制为 30 美元：\n\n```json\n{\n  \"budget_amount\": 30,\n  \"prevent_further_usage\": true,\n  \"budget_scope\": \"user\",\n  \"budget_entity_name\": \"\",\n  \"budget_type\": \"BundlePricing\",\n  \"budget_product_sku\": \"ai_credits\",\n  \"budget_alerting\": {\n    \"will_alert\": false,\n    \"alert_recipients\": []\n  },\n  \"user\": \"USERNAME\"\n}\n```\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## Get all budgets\n\n```\nGET /enterprises/{enterprise}/settings/billing/budgets\n```\n\nGets budgets for an enterprise. Enterprise owners and billing managers can view all budgets, and organization administrators can view budgets scoped to organizations and repositories they administer. A custom role holder with fine-grained read access to enterprise billing can view non-repository budgets; repository-scoped budgets require the organization administrator permissions described above. An installation access token for a GitHub App installed on the enterprise with read access to enterprise billing can list all budgets in the enterprise.\nEach page returns up to 100 budgets.\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- **`page`** (integer)\n  The page number of results to fetch.\n  Default: `1`\n\n- **`per_page`** (integer)\n  The number of results per page (max 100).\n  Default: `10`\n\n- **`scope`** (string)\n  Filter budgets by scope type.\n\nenterprise: Budgets that apply to the entire enterprise.\norganization: Budgets scoped to an organization in the enterprise.\nrepository: Budgets scoped to a repository.\ncost_center: Budgets scoped to a cost center.\nmulti_user_customer: Universal budgets that apply to all users in the enterprise.\nmulti_user_cost_center: Universal budgets that apply to all users in a cost center.\nuser: Budgets scoped to an individual user.\n  Can be one of: `enterprise`, `organization`, `repository`, `cost_center`, `multi_user_customer`, `multi_user_cost_center`, `user`\n\n- **`user`** (string)\n  Filter consumed amount details for budgets by the specified user login.\n\n### HTTP response status codes\n\n- **200** - Response when getting all budgets\n\n- **403** - Forbidden\n\n- **404** - Resource not found\n\n### Code examples\n\n#### Example 1: Status Code 200\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/enterprises/ENTERPRISE/settings/billing/budgets\n```\n\n**Response schema (Status: 200):**\n\n* `budgets`: required, array of objects:\n  * `id`: required, string\n  * `budget_type`: required, one of:\n    * **string, enum: `SkuPricing`**\n    * **string, enum: `ProductPricing`**\n  * `budget_amount`: required, integer\n  * `prevent_further_usage`: required, boolean\n  * `budget_scope`: required, string, enum: `enterprise`, `organization`, `repository`, `cost_center`, `multi_user_customer`, `multi_user_cost_center`, `user`\n  * `budget_entity_name`: string\n  * `user`: string\n  * `consumed_amount`: number\n  * `budget_product_sku`: required, string\n  * `budget_alerting`: required, object:\n    * `will_alert`: required, boolean\n    * `alert_recipients`: required, array of string\n  * `expires_at`: string, format: date\n* `user`: string\n* `effective_budget`: object:\n  * `id`: required, string\n  * `budget_amount`: required, integer\n  * `consumed_amount`: required, number\n* `has_next_page`: boolean\n* `total_count`: integer\n\n#### Example 2: Status Code 200\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/enterprises/ENTERPRISE/settings/billing/budgets\n```\n\n**Response schema (Status: 200):**\n\n* `budgets`: required, array of objects:\n  * `id`: required, string\n  * `budget_type`: required, one of:\n    * **string, enum: `SkuPricing`**\n    * **string, enum: `ProductPricing`**\n  * `budget_amount`: required, integer\n  * `prevent_further_usage`: required, boolean\n  * `budget_scope`: required, string, enum: `enterprise`, `organization`, `repository`, `cost_center`, `multi_user_customer`, `multi_user_cost_center`, `user`\n  * `budget_entity_name`: string\n  * `user`: string\n  * `consumed_amount`: number\n  * `budget_product_sku`: required, string\n  * `budget_alerting`: required, object:\n    * `will_alert`: required, boolean\n    * `alert_recipients`: required, array of string\n  * `expires_at`: string, format: date\n* `user`: string\n* `effective_budget`: object:\n  * `id`: required, string\n  * `budget_amount`: required, integer\n  * `consumed_amount`: required, number\n* `has_next_page`: boolean\n* `total_count`: integer\n\n## Create a budget\n\n```\nPOST /enterprises/{enterprise}/settings/billing/budgets\n```\n\nCreates a new budget for an enterprise. Enterprise owners and billing managers can create budgets scoped to the enterprise, all users in the enterprise, or any organization in it. Organization administrators can create budgets for their organizations, and repository-scoped budgets require administration of the repository's owning organization. A custom role holder with fine-grained write access to enterprise billing can create budgets scoped to a single user or a cost center, including all users in a cost center, without an additional administrator role; the role requirements above still apply to the other scopes. An installation access token for a GitHub App installed on the enterprise with write access to enterprise billing can create budgets for any target in the enterprise.\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- **`budget_amount`** (integer) (required)\n  The budget amount in whole dollars. For license-based products, this represents the number of licenses.\n\n- **`prevent_further_usage`** (boolean) (required)\n  Whether to prevent additional spending once the budget is exceeded. For user and multi_user_customer scopes, this must be true.\n\n- **`budget_alerting`** (object) (required)\n  - **`will_alert`** (boolean) (required)\n    Whether alerts are enabled for this budget. Rejected for user-scope as alerting is always disabled for them.\n  - **`alert_recipients`** (array of strings) (required)\n    Array of user login names who will receive alerts. Rejected for user-scope as alerting is always disabled for them.\n\n- **`budget_scope`** (string) (required)\n  The scope of the budget.\n\nenterprise: Apply the budget to the entire enterprise.\norganization: Apply the budget to a specific organization in the enterprise.\nrepository: Apply the budget to a specific repository.\ncost_center: Apply the budget to a specific cost center.\nmulti_user_customer: Apply a universal budget to all users in the enterprise.\nmulti_user_cost_center: Apply a universal budget to all users in a cost center.\nuser: Apply the budget to a single user.\n\nuser, multi_user_customer, and multi_user_cost_center scopes are only supported when budget_product_sku is ai_credits or premium_requests.\n  Can be one of: `enterprise`, `organization`, `repository`, `cost_center`, `multi_user_customer`, `multi_user_cost_center`, `user`\n\n- **`budget_entity_name`** (string)\n  The name of the entity to apply the budget to\n  Default: ``\n\n- **`budget_type`** (string) (required)\n  The type of pricing model used by the budget. Determines how budget_product_sku is interpreted.\n\nBundlePricing: Covers all AI credit SKUs. Set budget_product_sku to ai_credits.\nProductPricing: Covers all SKUs that belong to a product. Set budget_product_sku to a product such as actions or packages.\nSkuPricing: Covers a single, specific SKU. Set budget_product_sku to a SKU such as actions_linux.\n\n- **`budget_product_sku`** (string)\n  A single product or SKU that will be covered in the budget\n\n- **`user`** (string)\n  The username of the user for user scope budgets. This field is required when budget_scope is user.\n\n- **`expires_at`** (string)\n  The date the budget will expire in YYYY-MM-DD format. Only dates in the future are accepted.\nIf not provided, the budget will not expire.\nOnly supported for budgets with budget_scope of user\n\n### HTTP response status codes\n\n- **200** - Budget created successfully\n\n- **400** - Bad Request\n\n- **401** - Requires authentication\n\n- **403** - Forbidden\n\n- **404** - Feature not enabled\n\n- **422** - Validation failed, or the endpoint has been spammed.\n\n- **500** - Internal server error\n\n### Code examples\n\n#### Create budget example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X POST \\\n  https://api.github.com/enterprises/ENTERPRISE/settings/billing/budgets \\\n  -d '{\n  \"budget_amount\": 200,\n  \"prevent_further_usage\": true,\n  \"budget_scope\": \"enterprise\",\n  \"budget_entity_name\": \"\",\n  \"budget_type\": \"ProductPricing\",\n  \"budget_product_sku\": \"actions\",\n  \"budget_alerting\": {\n    \"will_alert\": false,\n    \"alert_recipients\": []\n  }\n}'\n```\n\n**Response schema (Status: 200):**\n\n* `message`: required, string\n* `budget`: required, object:\n  * `id`: string\n  * `budget_scope`: string, enum: `enterprise`, `organization`, `repository`, `cost_center`, `multi_user_customer`, `multi_user_cost_center`, `user`\n  * `budget_entity_name`: string\n  * `budget_amount`: integer, minimum: 0\n  * `prevent_further_usage`: boolean\n  * `budget_product_sku`: string\n  * `budget_type`: one of:\n    * **string, enum: `ProductPricing`**\n    * **string, enum: `SkuPricing`**\n  * `budget_alerting`: object:\n    * `will_alert`: boolean\n    * `alert_recipients`: array of string\n  * `expires_at`: string, format: date\n\n## Get a budget by ID\n\n```\nGET /enterprises/{enterprise}/settings/billing/budgets/{budget_id}\n```\n\nGets a budget by ID. Enterprise owners and billing managers can view any budget in the enterprise, and organization administrators can view budgets scoped to organizations and repositories they administer. A custom role holder with fine-grained read access to enterprise billing can view the budget unless it is scoped to a repository; repository-scoped budgets require the organization administrator permissions described above. An installation access token for a GitHub App installed on the enterprise with read access to enterprise billing can get any budget in the enterprise.\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- **`budget_id`** (string) (required)\n  The ID corresponding to the budget.\n\n### HTTP response status codes\n\n- **200** - Response when updating a budget\n\n- **400** - Bad Request\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/budgets/BUDGET_ID\n```\n\n**Response schema (Status: 200):**\n\n* `id`: required, string\n* `budget_scope`: required, string, enum: `enterprise`, `organization`, `repository`, `cost_center`, `multi_user_customer`, `multi_user_cost_center`, `user`\n* `budget_entity_name`: required, string\n* `user`: string\n* `budget_amount`: required, integer\n* `prevent_further_usage`: required, boolean\n* `budget_product_sku`: required, string\n* `budget_type`: required, one of:\n  * **string, enum: `ProductPricing`**\n  * **string, enum: `SkuPricing`**\n* `budget_alerting`: required, object:\n  * `will_alert`: boolean\n  * `alert_recipients`: array of string\n\n## Update a budget\n\n```\nPATCH /enterprises/{enterprise}/settings/billing/budgets/{budget_id}\n```\n\nUpdates an existing budget for an enterprise. Enterprise owners and billing managers can update budgets scoped to the enterprise, all users in the enterprise, or any organization in it. Organization administrators can update budgets for their organizations, and repository-scoped budgets require administration of the repository's owning organization. A custom role holder with fine-grained write access to enterprise billing can update budgets scoped to a single user or a cost center, including all users in a cost center, without an additional administrator role; the role requirements above still apply to the other scopes. An installation access token for a GitHub App installed on the enterprise with write access to enterprise billing can update any budget in the enterprise.\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- **`budget_id`** (string) (required)\n  The unique identifier of the budget\n\n#### Body parameters\n\n- **`budget_amount`** (integer)\n  The budget amount in whole dollars. For license-based products, this represents the number of licenses.\n\n- **`prevent_further_usage`** (boolean)\n  Whether to prevent additional spending once the budget is exceeded. For budgets with user or multi_user_customer scope, this must remain true.\n\n- **`budget_alerting`** (object)\n  - **`will_alert`** (boolean)\n    Whether alerts are enabled for this budget. Ignored for user-scope as alerting is always disabled for them.\n  - **`alert_recipients`** (array of strings)\n    Array of user login names who will receive alerts. Ignored for user-scope as alerting is always disabled for them.\n\n- **`budget_scope`** (string)\n  The scope of the budget.\n\nenterprise: Apply the budget to the entire enterprise.\norganization: Apply the budget to a specific organization in the enterprise.\nrepository: Apply the budget to a specific repository.\ncost_center: Apply the budget to a specific cost center.\nmulti_user_customer: Apply a universal budget to all users in the enterprise.\nmulti_user_cost_center: Apply a universal budget to all users in a cost center.\nuser: Apply the budget to a single user.\n  Can be one of: `enterprise`, `organization`, `repository`, `cost_center`, `multi_user_customer`, `multi_user_cost_center`, `user`\n\n- **`budget_entity_name`** (string)\n  The name of the entity to apply the budget to\n\n- **`budget_type`** (string)\n  The type of pricing model used by the budget. Determines how budget_product_sku is interpreted.\n\nBundlePricing: Covers all AI credit SKUs. Set budget_product_sku to ai_credits.\nProductPricing: Covers all SKUs that belong to a product. Set budget_product_sku to a product such as actions or packages.\nSkuPricing: Covers a single, specific SKU. Set budget_product_sku to a SKU such as actions_linux.\n\n- **`budget_product_sku`** (string)\n  A single product or SKU that will be covered in the budget\n\n- **`user`** (string)\n  The username of the user for user scope budgets.\n\n- **`expires_at`** (string or null or integer)\n  The date the budget will expire in YYYY-MM-DD format. Only dates in the future are accepted.\nIf not set, the budget will not expire. Setting to null or 0 will remove the expiration date from a budget if set.\nOnly supported for budgets with budget_scope of user\n\n### HTTP response status codes\n\n- **200** - Budget updated successfully\n\n- **400** - Bad Request\n\n- **401** - Requires authentication\n\n- **403** - Forbidden\n\n- **404** - Budget not found or feature not enabled\n\n- **422** - Validation failed, or the endpoint has been spammed.\n\n- **500** - Internal server error\n\n- **503** - Service unavailable\n\n### Code examples\n\n#### Update budget example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X PATCH \\\n  https://api.github.com/enterprises/ENTERPRISE/settings/billing/budgets/BUDGET_ID \\\n  -d '{\n  \"prevent_further_usage\": false,\n  \"budget_amount\": 10,\n  \"budget_alerting\": {\n    \"will_alert\": false,\n    \"alert_recipients\": []\n  }\n}'\n```\n\n**Response schema (Status: 200):**\n\n* `message`: required, string\n* `budget`: required, object:\n  * `id`: string\n  * `budget_scope`: string, enum: `enterprise`, `organization`, `repository`, `cost_center`, `multi_user_customer`, `multi_user_cost_center`, `user`\n  * `budget_entity_name`: string\n  * `user`: string\n  * `consumed_amount`: number\n  * `budget_amount`: integer, minimum: 0\n  * `prevent_further_usage`: boolean\n  * `budget_product_sku`: string\n  * `budget_type`: one of:\n    * **string, enum: `ProductPricing`**\n    * **string, enum: `SkuPricing`**\n  * `budget_alerting`: object:\n    * `will_alert`: boolean\n    * `alert_recipients`: array of string\n  * `expires_at`: string, format: date\n\n## Delete a budget\n\n```\nDELETE /enterprises/{enterprise}/settings/billing/budgets/{budget_id}\n```\n\nDeletes a budget by ID. Enterprise owners and billing managers can delete any budget in the enterprise, organization administrators can delete budgets scoped to organizations they administer, and repository administrators can delete budgets scoped to repositories they administer in those organizations. A custom role holder with fine-grained write access to enterprise billing does not by itself get permission to delete a budget for a target they do not administer. An installation access token for a GitHub App installed on the enterprise with write access to enterprise billing can delete any budget in the enterprise.\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- **`budget_id`** (string) (required)\n  The ID corresponding to the budget.\n\n### HTTP response status codes\n\n- **200** - Response when deleting a budget\n\n- **400** - Bad Request\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 DELETE \\\n  https://api.github.com/enterprises/ENTERPRISE/settings/billing/budgets/BUDGET_ID\n```\n\n**Response schema (Status: 200):**\n\n* `message`: required, string\n* `id`: required, string\n\n## Get user states for a multi-user budget\n\n```\nGET /enterprises/{enterprise}/settings/billing/budgets/{budget_id}/user-states\n```\n\nLists per-user budget state for a multi-user customer scoped budget. Enterprise owners and billing managers can view state across the enterprise, and organization administrators can view state for budgets scoped to organizations they administer. A custom role holder with fine-grained read access to enterprise billing can also view budget user states. An installation access token for a GitHub App installed on the enterprise with read access to enterprise billing can list user states for any multi-user budget in the enterprise.\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- **`budget_id`** (string) (required)\n  The ID corresponding to the budget.\n\n- **`page`** (integer)\n  The page number of results to fetch.\n\n- **`per_page`** (integer)\n  The number of results per page.\n\n- **`sort_order`** (string)\n  Sort order for results. 0 for descending, 1 for ascending.\n  Can be one of: `0`, `1`\n\n- **`user`** (string)\n  Filter user states to a specific user login.\n\n- **`threshold_lower_bound`** (integer)\n  Filter user states whose threshold percentage is at or above this value.\n\n- **`threshold_upper_bound`** (integer)\n  Filter user states whose threshold percentage is at or below this value.\n\n### HTTP response status codes\n\n- **200** - Response when getting per-user states for a multi-user budget\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/budgets/BUDGET_ID/user-states\n```\n\n**Response schema (Status: 200):**\n\n* `user_states`: required, array of objects:\n  * `user`: string\n  * `consumed_amount`: required, number\n  * `target_amount`: required, number\n  * `override_budget_id`: string\n* `has_next_page`: required, boolean\n* `total_count`: required, integer"}