Budgets - GitHub Enterprise Cloud Docs

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:

{
  "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"
}

Get all budgets

Gets budgets for an enterprise. Enterprise owners and billing managers can view all budgets. Organization administrators can view budgets scoped to organizations and repositories they administer. Each page returns up to 100 budgets.

Fine-grained access tokens for "Get all budgets"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Enterprise billing" enterprise permissions (read)

Parameters for "Get all budgets"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.

Query parameters
Name, Type, Description
`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. `enterprise`: Budgets that apply to the entire enterprise. `organization`: Budgets scoped to an organization in the enterprise. `repository`: Budgets scoped to a repository. `cost_center`: Budgets scoped to a cost center. `multi_user_customer`: Universal budgets that apply to all users in the enterprise. `multi_user_cost_center`: Universal budgets that apply to all users in a cost center. `user`: Budgets scoped to an individual user. Can be one of: `enterprise`, `organization`, `repository`, `cost_center`, `multi_user_customer`, `multi_user_cost_center`, `user`
`user` string Filter consumed amount details for budgets by the specified user login.

HTTP response status codes for "Get all budgets"

Status code	Description
`200`	Response when getting all budgets
`403`	Forbidden
`404`	Resource not found

Code samples for "Get all budgets"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request examples

Select the example type

get/enterprises/{enterprise}/settings/billing/budgets

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/enterprises/ENTERPRISE/settings/billing/budgets

Response when getting all budgets

Status: 200

{
  "budgets": [
    {
      "id": "2066deda-923f-43f9-88d2-62395a28c0cdd",
      "budget_type": "ProductPricing",
      "budget_product_skus": [
        "actions"
      ],
      "budget_scope": "enterprise",
      "budget_amount": 1000,
      "prevent_further_usage": true,
      "budget_alerting": {
        "will_alert": true,
        "alert_recipients": [
          "enterprise-admin",
          "billing-manager"
        ]
      }
    },
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "budget_type": "SkuPricing",
      "budget_product_skus": [
        "actions_linux"
      ],
      "budget_scope": "organization",
      "budget_amount": 500,
      "prevent_further_usage": false,
      "budget_alerting": {
        "will_alert": true,
        "alert_recipients": [
          "org-owner"
        ]
      }
    },
    {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "budget_type": "ProductPricing",
      "budget_product_skus": [
        "packages"
      ],
      "budget_scope": "cost_center",
      "budget_amount": 250,
      "prevent_further_usage": true,
      "budget_alerting": {
        "will_alert": false,
        "alert_recipients": []
      }
    }
  ],
  "has_next_page": false,
  "total_count": 3
}

Create a budget

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

Fine-grained access tokens for "Create a budget"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Enterprise billing" enterprise permissions (write)

Parameters for "Create a budget"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.

Name, Type, Description

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

Properties of budget_alerting

Name, Type, Description
`will_alert` boolean Required Whether alerts are enabled for this budget. Rejected for user-scope as alerting is always disabled for them.
`alert_recipients` array of strings Required Array of user login names who will receive alerts. Rejected for user-scope as alerting is always disabled for them.

budget_scope string Required

The scope of the budget.

enterprise: Apply the budget to the entire enterprise.
organization: Apply the budget to a specific organization in the enterprise.
repository: Apply the budget to a specific repository.
cost_center: Apply the budget to a specific cost center.
multi_user_customer: Apply a universal budget to all users in the enterprise.
multi_user_cost_center: Apply a universal budget to all users in a cost center.
user: Apply the budget to a single user.

user, multi_user_customer, and multi_user_cost_center 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, multi_user_cost_center, 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 for "Create a budget"

Status code	Description
`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 samples for "Create a budget"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

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

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  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":[]}}'

Budget created successfully

Status: 200

{
  "message": "Budget successfully created.",
  "budget": {
    "id": "f5236c62-157f-4d8f-a79e-ffb91058ee97",
    "budget_type": "ProductPricing",
    "budget_product_sku": "actions",
    "budget_scope": "organization",
    "budget_entity_name": "example-organization",
    "budget_amount": 100,
    "prevent_further_usage": true,
    "budget_alerting": {
      "will_alert": false,
      "alert_recipients": []
    }
  }
}

Get a budget by ID

Gets a budget by ID. Enterprise owners and billing managers can view any budget in the enterprise. Organization administrators can view budgets scoped to organizations and repositories they administer.

Fine-grained access tokens for "Get a budget by ID"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Enterprise billing" enterprise permissions (read)

Parameters for "Get a budget by ID"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`budget_id` string Required The ID corresponding to the budget.

HTTP response status codes for "Get a budget by ID"

Status code	Description
`200`	Response when updating a budget
`400`	Bad Request
`403`	Forbidden
`404`	Resource not found
`500`	Internal Error
`503`	Service unavailable

Code samples for "Get a budget by ID"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/enterprises/{enterprise}/settings/billing/budgets/{budget_id}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/enterprises/ENTERPRISE/settings/billing/budgets/BUDGET_ID

Response when updating a budget

Status: 200

{
  "id": "2066deda-923f-43f9-88d2-62395a28c0cdd",
  "budget_type": "ProductPricing",
  "budget_product_sku": "actions_linux",
  "budget_scope": "repository",
  "budget_entity_name": "example-repo-name",
  "budget_amount": 0,
  "prevent_further_usage": true,
  "budget_alerting": {
    "will_alert": true,
    "alert_recipients": [
      "mona",
      "lisa"
    ]
  }
}

Update a budget

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

Fine-grained access tokens for "Update a budget"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Enterprise billing" enterprise permissions (write)

Parameters for "Update a budget"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name
`budget_id` string Required The unique identifier of the budget

Name, Type, Description

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

Properties of budget_alerting

Name, Type, Description
`will_alert` boolean Whether alerts are enabled for this budget. Ignored for user-scope as alerting is always disabled for them.
`alert_recipients` array of strings Array of user login names who will receive alerts. Ignored for user-scope as alerting is always disabled for them.

budget_scope string

The scope of the budget.

enterprise: Apply the budget to the entire enterprise.
organization: Apply the budget to a specific organization in the enterprise.
repository: Apply the budget to a specific repository.
cost_center: Apply the budget to a specific cost center.
multi_user_customer: Apply a universal budget to all users in the enterprise.
multi_user_cost_center: Apply a universal budget to all users in a cost center.
user: Apply the budget to a single user.

Can be one of: enterprise, organization, repository, cost_center, multi_user_customer, multi_user_cost_center, 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 for "Update a budget"

Status code	Description
`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 samples for "Update a budget"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

patch/enterprises/{enterprise}/settings/billing/budgets/{budget_id}

curl -L \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  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":[]}}'

Budget updated successfully

Status: 200

{
  "message": "Budget successfully updated.",
  "budget": {
    "id": "2066deda-923f-43f9-88d2-62395a28c0cdd",
    "budget_type": "ProductPricing",
    "budget_product_sku": "actions_linux",
    "budget_scope": "repository",
    "budget_entity_name": "org-name/example-repo-name",
    "budget_amount": 10,
    "prevent_further_usage": true,
    "budget_alerting": {
      "will_alert": true,
      "alert_recipients": [
        "mona",
        "lisa"
      ]
    }
  }
}

Delete a budget

Deletes 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.

Fine-grained access tokens for "Delete a budget"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Enterprise billing" enterprise permissions (write)

Parameters for "Delete a budget"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`budget_id` string Required The ID corresponding to the budget.

HTTP response status codes for "Delete a budget"

Status code	Description
`200`	Response when deleting a budget
`400`	Bad Request
`403`	Forbidden
`404`	Resource not found
`500`	Internal Error
`503`	Service unavailable

Code samples for "Delete a budget"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

delete/enterprises/{enterprise}/settings/billing/budgets/{budget_id}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/enterprises/ENTERPRISE/settings/billing/budgets/BUDGET_ID

Response when deleting a budget

Status: 200

{
  "message": "Budget successfully deleted.",
  "budget_id": "2c1feb79-3947-4dc8-a16e-80cbd732cc0b"
}

Get user states for a multi-user budget

Lists per-user budget state for a multi-user customer scoped budget. Enterprise owners and billing managers can view state across the enterprise. Organization administrators can view state for budgets scoped to organizations they administer.

Fine-grained access tokens for "Get user states for a multi-user budget"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

"Enterprise billing" enterprise permissions (read)

Parameters for "Get user states for a multi-user budget"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.
`budget_id` string Required The ID corresponding to the budget.

Query parameters
Name, Type, Description
`page` integer The page number of results to fetch.
`per_page` integer The number of results per page.
`sort_order` string Sort order for results. `0` for descending, `1` for ascending. Can be one of: `0`, `1`
`user` string Filter user states to a specific user login.
`threshold_lower_bound` integer Filter user states whose threshold percentage is at or above this value.
`threshold_upper_bound` integer Filter user states whose threshold percentage is at or below this value.

HTTP response status codes for "Get user states for a multi-user budget"

Status code	Description
`200`	Response when getting per-user states for a multi-user budget
`403`	Forbidden
`404`	Resource not found
`500`	Internal Error
`503`	Service unavailable

Code samples for "Get user states for a multi-user budget"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/enterprises/{enterprise}/settings/billing/budgets/{budget_id}/user-states

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/enterprises/ENTERPRISE/settings/billing/budgets/BUDGET_ID/user-states

Response when getting per-user states for a multi-user budget

Status: 200

{
  "user_states": [
    {
      "user": "octocat",
      "consumed_amount": 50.5,
      "target_amount": 1000
    },
    {
      "user": "monalisa",
      "consumed_amount": 250,
      "target_amount": 1000,
      "override_budget_id": "2066deda-923f-43f9-88d2-62395a28c0cdd"
    }
  ],
  "has_next_page": false,
  "total_count": 2
}