BERJAYA

Get all budgets

Note

This endpoint is in public preview and is subject to change.

Gets all budgets for an enterprise. The authenticated user must be an enterprise admin or billing manager.

Fine-grained access tokens for "Get all budgets"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

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 the results to fetch. For more information, see "Using pagination in the REST API." Default: `1`
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: `30`
`page_size` integer The number of results per page (max 10). Default: `10`
`scope` string Filter budgets by scope type. Can be one of: `enterprise`, `organization`, `repository`, `cost-center`

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 example

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

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

Create a budget

Note

This endpoint is in public preview and is subject to change.

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 does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

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

budget_alerting object Required

Properties of budget_alerting

Name, Type, Description
`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

Can be one of: enterprise, organization, repository, cost_center

budget_entity_name string

The name of the entity to apply the budget to

Default: ""

budget_type string Required

The type of pricing for the budget

Can be one of: ProductPricing, SkuPricing

budget_product_sku string

A single product or SKU that will be covered in the budget

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: 2022-11-28" \
  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."
}

Get a budget by ID

Note

This endpoint is in public preview and is subject to change.

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

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

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

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: 2022-11-28" \
  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

Note

This endpoint is in public preview and is subject to change.

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 does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

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

budget_alerting object

Properties of budget_alerting

Name, Type, Description
`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

budget_entity_name string

The name of the entity to apply the budget to

budget_type string

The type of pricing for the budget

Can be one of: ProductPricing, SkuPricing

budget_product_sku string

A single product or SKU that will be covered in the budget

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: 2022-11-28" \
  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": 0,
    "prevent_further_usage": true,
    "budget_alerting": {
      "will_alert": true,
      "alert_recipients": [
        "mona",
        "lisa"
      ]
    }
  }
}

Delete a budget

Note

This endpoint is in public preview and is subject to change.

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

Fine-grained access tokens for "Delete a budget"

This endpoint does not work with GitHub App user access tokens, GitHub App installation access tokens, or fine-grained personal access tokens.

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: 2022-11-28" \
  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"
}

Budgets

Request example

Response when getting all budgets

Request example

Budget created successfully

Request example

Response when updating a budget

Request example

Budget updated successfully

Request example

Response when deleting a budget