Skip to content
forgit api docs

Get all budgets for an organization

GET
/organizations/{org}/settings/billing/budgets

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

API method documentation

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
org
required
string

The organization name. The name is not case sensitive.

Query Parameters

Section titled “ Query Parameters ”
page
integer
default: 1

The page number of the results to fetch.

per_page
integer
default: 10

The number of results per page (max 100).

scope
string
Allowed values: enterprise organization repository cost_center multi_user_customer user

Filter budgets by scope type.

  • organization: Budgets scoped to the organization.
  • repository: Budgets scoped to a repository.
  • multi_user_customer: Universal budgets that apply to all users in the organization.
  • user: Budgets scoped to an individual user.
user
string

Filter consumed amount details for budgets by the specified user login.

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Response when getting all budgets

Media type application/json
object
budgets
required

Array of budget objects for the enterprise

Array<object>
object
id
required

The unique identifier for the budget

string
budget_type
required
One of:
string
Allowed values: SkuPricing
budget_amount
required

The budget amount limit in whole dollars. For license-based products, this represents the number of licenses.

integer
prevent_further_usage
required

The type of limit enforcement for the budget

boolean
budget_scope
required

The scope of the budget

string
Allowed values: enterprise organization repository cost_center multi_user_customer multi_user_cost_center user
budget_entity_name

The name of the entity for the budget (enterprise does not require a name).

string
user

The user login when the budget is scoped to a single user (user scope).

string
budget_product_sku
required

A single product or sku to apply the budget to.

string
budget_alerting
required
object
will_alert
required

Whether alerts are enabled for this budget

boolean
alert_recipients
required

Array of user login names who will receive alerts

Array<string>
user

User login included when the response is scoped with the user query parameter.

string
effective_budget

Effective user-level budget details returned when the response is scoped with the user query parameter.

object
id
required

The unique identifier of the effective budget.

string
budget_amount
required

The budget amount for the effective budget.

integer
consumed_amount
required

The consumed amount for the specified user within the effective budget.

number
has_next_page

Indicates if there are more pages of results available (maps to hasNextPage from billing platform)

boolean
total_count

Total number of budgets matching the query

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

403

Section titled “ 403 ”

Forbidden

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

404

Section titled “ 404 ”

Resource not found

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

500

Section titled “ 500 ”

Internal Error

Media type application/json
Basic Error

Basic Error

object
message
string
documentation_url
string
url
string
status
string
Example generated 
{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}