# Budgets

Use the REST API to get budget information.

> [!IMPORTANT]
> The request body schema below is missing a required field. When `budget_scope` is `user`, you must also include a `user` field set to the GitHub username the budget applies to. If you omit this field, the API returns `HTTP 400: Missing required fields: budget_entity_name`. For user-scoped budgets, `budget_entity_name` can be an empty string.

The following example creates a user-scoped budget that limits a single user's monthly Copilot AI credits to $30 USD:

```json
{
  "budget_amount": 30,
  "prevent_further_usage": true,
  "budget_scope": "user",
  "budget_entity_name": "",
  "budget_type": "BundlePricing",
  "budget_product_sku": "ai_credits",
  "budget_alerting": {
    "will_alert": false,
    "alert_recipients": []
  },
  "user": "USERNAME"
}
```

> [!NOTE]
> 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.

## Get all budgets

```
GET /enterprises/{enterprise}/settings/billing/budgets
```

Gets all budgets for an enterprise. The authenticated user must be an enterprise admin or billing manager.
Each page returns up to 100 budgets.

### Parameters

#### Headers

- **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

- **`enterprise`** (string) (required)
  The slug version of the enterprise name.

- **`page`** (integer)
  The page number of results to fetch.
  Default: `1`

- **`per_page`** (integer)
  The number of results per page (max 100).
  Default: `10`

- **`scope`** (string)
  Filter budgets by scope type.
  Can be one of: `enterprise`, `organization`, `repository`, `cost_center`, `multi_user_customer`, `user`

- **`user`** (string)
  Filter consumed amount details for budgets by the specified user login.

### HTTP response status codes

- **200** - Response when getting all budgets

- **403** - Forbidden

- **404** - Resource not found

### Code examples

#### Example 1: Status Code 200

**Request:**

```curl
curl -L \
  -X GET \
  https://api.github.com/enterprises/ENTERPRISE/settings/billing/budgets
```

**Response schema (Status: 200):**

* `budgets`: required, array of objects:
  * `id`: required, string
  * `budget_type`: required, one of:
    * **string, enum: `SkuPricing`**
    * **string, enum: `ProductPricing`**
  * `budget_amount`: required, integer
  * `prevent_further_usage`: required, boolean
  * `budget_scope`: required, string, enum: `enterprise`, `organization`, `repository`, `cost_center`, `multi_user_customer`, `user`
  * `budget_entity_name`: string
  * `user`: string
  * `budget_product_sku`: required, string
  * `budget_alerting`: required, object:
    * `will_alert`: required, boolean
    * `alert_recipients`: required, array of string
* `user`: string
* `effective_budget`: object:
  * `id`: required, string
  * `budget_amount`: required, integer
  * `consumed_amount`: required, number
* `has_next_page`: boolean
* `total_count`: integer

#### Example 2: Status Code 200

**Request:**

```curl
curl -L \
  -X GET \
  https://api.github.com/enterprises/ENTERPRISE/settings/billing/budgets
```

**Response schema (Status: 200):**

* `budgets`: required, array of objects:
  * `id`: required, string
  * `budget_type`: required, one of:
    * **string, enum: `SkuPricing`**
    * **string, enum: `ProductPricing`**
  * `budget_amount`: required, integer
  * `prevent_further_usage`: required, boolean
  * `budget_scope`: required, string, enum: `enterprise`, `organization`, `repository`, `cost_center`, `multi_user_customer`, `user`
  * `budget_entity_name`: string
  * `user`: string
  * `budget_product_sku`: required, string
  * `budget_alerting`: required, object:
    * `will_alert`: required, boolean
    * `alert_recipients`: required, array of string
* `user`: string
* `effective_budget`: object:
  * `id`: required, string
  * `budget_amount`: required, integer
  * `consumed_amount`: required, number
* `has_next_page`: boolean
* `total_count`: integer

## Create a budget

```
POST /enterprises/{enterprise}/settings/billing/budgets
```

Creates a new budget for an enterprise. The authenticated user must be an enterprise admin, organization admin, or billing manager of the enterprise.

### Parameters

#### Headers

- **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

- **`enterprise`** (string) (required)
  The slug version of the enterprise name.

#### Body parameters

- **`budget_amount`** (integer) (required)
  The budget amount in whole dollars. For license-based products, this represents the number of licenses.

- **`prevent_further_usage`** (boolean) (required)
  Whether to prevent additional spending once the budget is exceeded. For user and multi_user_customer scopes, this must be true.

- **`budget_alerting`** (object) (required)
  - **`will_alert`** (boolean) (required)
    Whether alerts are enabled for this budget
  - **`alert_recipients`** (array of strings) (required)
    Array of user login names who will receive alerts

- **`budget_scope`** (string) (required)
  The scope of the budget. user and multi_user_customer scopes are only supported when budget_product_sku is ai_credits or premium_requests.
  Can be one of: `enterprise`, `organization`, `repository`, `cost_center`, `multi_user_customer`, `user`

- **`budget_entity_name`** (string)
  The name of the entity to apply the budget to
  Default: ``

- **`budget_type`** (string) (required)
  The type of pricing model used by the budget. Determines how budget_product_sku is interpreted.

BundlePricing: Covers all AI credit SKUs. Set budget_product_sku to ai_credits.
ProductPricing: Covers all SKUs that belong to a product. Set budget_product_sku to a product such as actions or packages.
SkuPricing: Covers a single, specific SKU. Set budget_product_sku to a SKU such as actions_linux.

- **`budget_product_sku`** (string)
  A single product or SKU that will be covered in the budget

- **`user`** (string)
  The username of the user for user scope budgets. This field is required when budget_scope is user.

### HTTP response status codes

- **200** - Budget created successfully

- **400** - Bad Request

- **401** - Requires authentication

- **403** - Forbidden

- **404** - Feature not enabled

- **422** - Validation failed, or the endpoint has been spammed.

- **500** - Internal server error

### Code examples

#### Create budget example

**Request:**

```curl
curl -L \
  -X POST \
  https://api.github.com/enterprises/ENTERPRISE/settings/billing/budgets \
  -d '{
  "budget_amount": 200,
  "prevent_further_usage": true,
  "budget_scope": "enterprise",
  "budget_entity_name": "",
  "budget_type": "ProductPricing",
  "budget_product_sku": "actions",
  "budget_alerting": {
    "will_alert": false,
    "alert_recipients": []
  }
}'
```

**Response schema (Status: 200):**

* `message`: required, string
* `budget`: required, object:
  * `id`: string
  * `budget_scope`: string, enum: `enterprise`, `organization`, `repository`, `cost_center`, `multi_user_customer`, `user`
  * `budget_entity_name`: string
  * `budget_amount`: integer, minimum: 0
  * `prevent_further_usage`: boolean
  * `budget_product_sku`: string
  * `budget_type`: one of:
    * **string, enum: `ProductPricing`**
    * **string, enum: `SkuPricing`**
  * `budget_alerting`: object:
    * `will_alert`: boolean
    * `alert_recipients`: array of string

## Get a budget by ID

```
GET /enterprises/{enterprise}/settings/billing/budgets/{budget_id}
```

Gets a budget by ID. The authenticated user must be an enterprise admin or billing manager.

### Parameters

#### Headers

- **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

- **`enterprise`** (string) (required)
  The slug version of the enterprise name.

- **`budget_id`** (string) (required)
  The ID corresponding to the budget.

### HTTP response status codes

- **200** - Response when updating a budget

- **400** - Bad Request

- **403** - Forbidden

- **404** - Resource not found

- **500** - Internal Error

- **503** - Service unavailable

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X GET \
  https://api.github.com/enterprises/ENTERPRISE/settings/billing/budgets/BUDGET_ID
```

**Response schema (Status: 200):**

* `id`: required, string
* `budget_scope`: required, string, enum: `enterprise`, `organization`, `repository`, `cost_center`, `multi_user_customer`, `user`
* `budget_entity_name`: required, string
* `user`: string
* `budget_amount`: required, integer
* `prevent_further_usage`: required, boolean
* `budget_product_sku`: required, string
* `budget_type`: required, one of:
  * **string, enum: `ProductPricing`**
  * **string, enum: `SkuPricing`**
* `budget_alerting`: required, object:
  * `will_alert`: boolean
  * `alert_recipients`: array of string

## Update a budget

```
PATCH /enterprises/{enterprise}/settings/billing/budgets/{budget_id}
```

Updates an existing budget for an enterprise. The authenticated user must be an enterprise admin, organization admin, or billing manager of the enterprise.

### Parameters

#### Headers

- **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

- **`enterprise`** (string) (required)
  The slug version of the enterprise name

- **`budget_id`** (string) (required)
  The unique identifier of the budget

#### Body parameters

- **`budget_amount`** (integer)
  The budget amount in whole dollars. For license-based products, this represents the number of licenses.

- **`prevent_further_usage`** (boolean)
  Whether to prevent additional spending once the budget is exceeded. For budgets with user or multi_user_customer scope, this must remain true.

- **`budget_alerting`** (object)
  - **`will_alert`** (boolean)
    Whether alerts are enabled for this budget
  - **`alert_recipients`** (array of strings)
    Array of user login names who will receive alerts

- **`budget_scope`** (string)
  The scope of the budget
  Can be one of: `enterprise`, `organization`, `repository`, `cost_center`, `multi_user_customer`, `user`

- **`budget_entity_name`** (string)
  The name of the entity to apply the budget to

- **`budget_type`** (string)
  The type of pricing model used by the budget. Determines how budget_product_sku is interpreted.

BundlePricing: Covers all AI credit SKUs. Set budget_product_sku to ai_credits.
ProductPricing: Covers all SKUs that belong to a product. Set budget_product_sku to a product such as actions or packages.
SkuPricing: Covers a single, specific SKU. Set budget_product_sku to a SKU such as actions_linux.

- **`budget_product_sku`** (string)
  A single product or SKU that will be covered in the budget

- **`user`** (string)
  The username of the user for user scope budgets.

### HTTP response status codes

- **200** - Budget updated successfully

- **400** - Bad Request

- **401** - Requires authentication

- **403** - Forbidden

- **404** - Budget not found or feature not enabled

- **422** - Validation failed, or the endpoint has been spammed.

- **500** - Internal server error

- **503** - Service unavailable

### Code examples

#### Update budget example

**Request:**

```curl
curl -L \
  -X PATCH \
  https://api.github.com/enterprises/ENTERPRISE/settings/billing/budgets/BUDGET_ID \
  -d '{
  "prevent_further_usage": false,
  "budget_amount": 10,
  "budget_alerting": {
    "will_alert": false,
    "alert_recipients": []
  }
}'
```

**Response schema (Status: 200):**

* `message`: required, string
* `budget`: required, object:
  * `id`: string
  * `budget_scope`: string, enum: `enterprise`, `organization`, `repository`, `cost_center`
  * `budget_entity_name`: string
  * `budget_amount`: integer, minimum: 0
  * `prevent_further_usage`: boolean
  * `budget_product_sku`: string
  * `budget_type`: one of:
    * **string, enum: `ProductPricing`**
    * **string, enum: `SkuPricing`**
  * `budget_alerting`: object:
    * `will_alert`: boolean
    * `alert_recipients`: array of string

## Delete a budget

```
DELETE /enterprises/{enterprise}/settings/billing/budgets/{budget_id}
```

Deletes a budget by ID. The authenticated user must be an enterprise admin.

### Parameters

#### Headers

- **`accept`** (string)
  Setting to `application/vnd.github+json` is recommended.

#### Path and query parameters

- **`enterprise`** (string) (required)
  The slug version of the enterprise name.

- **`budget_id`** (string) (required)
  The ID corresponding to the budget.

### HTTP response status codes

- **200** - Response when deleting a budget

- **400** - Bad Request

- **403** - Forbidden

- **404** - Resource not found

- **500** - Internal Error

- **503** - Service unavailable

### Code examples

#### Example

**Request:**

```curl
curl -L \
  -X DELETE \
  https://api.github.com/enterprises/ENTERPRISE/settings/billing/budgets/BUDGET_ID
```

**Response schema (Status: 200):**

* `message`: required, string
* `id`: required, string