Budgets - List

Lists all budgets for the defined scope.

GET https://management.azure.com/{scope}/providers/Microsoft.Consumption/budgets?api-version=2019-10-01

URI Parameters

Name In Required Type Description
scope
path True
  • string

The scope associated with budget operations. This includes '/subscriptions/{subscriptionId}/' for subscription scope, '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}' for resourceGroup scope, '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}' for Billing Account scope, '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/departments/{departmentId}' for Department scope, '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/enrollmentAccounts/{enrollmentAccountId}' for EnrollmentAccount scope, '/providers/Microsoft.Management/managementGroups/{managementGroupId}' for Management Group scope, '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/billingProfiles/{billingProfileId}' for billingProfile scope, 'providers/Microsoft.Billing/billingAccounts/{billingAccountId}/invoiceSections/{invoiceSectionId}' for invoiceSection scope.

api-version
query True
  • string

Version of the API to be used with the client request. The current version is 2019-10-01.

Responses

Name Type Description
200 OK

OK. The request has succeeded.

Other Status Codes

Error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
user_impersonation impersonate your user account

Examples

BudgetsList

Sample Request

GET https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Consumption/budgets?api-version=2019-10-01

Sample Response

{
  "value": [
    {
      "id": "subscriptions/{subscription-id}/providers/Microsoft.Consumption/budgets/TestBudget",
      "name": "TestBudget",
      "type": "Microsoft.Consumption/budgets",
      "eTag": "\"1d34d012214157f\"",
      "properties": {
        "category": "Cost",
        "amount": 100.65,
        "timeGrain": "Monthly",
        "timePeriod": {
          "startDate": "2017-10-01T00:00:00Z",
          "endDate": "2018-10-31T00:00:00Z"
        },
        "filters": {
          "resourceGroups": [
            "MYDEVTESTRG"
          ],
          "resources": [
            "/subscriptions/{subscription-id}/resourceGroups/MYDEVTESTRG/providers/Microsoft.Compute/virtualMachines/MYVM2",
            "/subscriptions/{subscription-id}/resourceGroups/MYDEVTESTRG/providers/Microsoft.Compute/virtualMachines/platformcloudplatformGeneric1"
          ],
          "meters": [
            "00000000-0000-0000-0000-000000000000"
          ],
          "tags": {
            "category": [
              "Dev",
              "Prod"
            ],
            "department": [
              "engineering",
              "sales"
            ]
          }
        },
        "currentSpend": {
          "amount": 80.89,
          "unit": "USD"
        },
        "notifications": {
          "Actual_GreaterThan_80_Percent": {
            "enabled": true,
            "operator": "GreaterThan",
            "threshold": 80,
            "contactEmails": [
              "johndoe@contoso.com",
              "janesmith@contoso.com"
            ],
            "contactRoles": [
              "Contributor",
              "Reader"
            ]
          },
          "Actual_GreaterThanOrEqualTo_90_Percent": {
            "enabled": true,
            "operator": "GreaterThanOrEqualTo",
            "threshold": 90,
            "contactEmails": [
              "johndoe@contoso.com",
              "janesmith@contoso.com"
            ],
            "contactRoles": [
              "Contributor",
              "Reader"
            ],
            "contactGroups": [
              "/subscriptions/{subscription-id}/resourceGroups/MYDEVTESTRG/providers/microsoft.insights/actionGroups/SampleActionGroup"
            ]
          }
        }
      }
    },
    {
      "id": "subscriptions/{subscription-id}/providers/Microsoft.Consumption/budgets/TestBudget",
      "name": "TestBudget",
      "type": "Microsoft.Consumption/budgets",
      "eTag": "\"1d34d012214157f\"",
      "properties": {
        "category": "Cost",
        "amount": 600.65,
        "timeGrain": "Monthly",
        "timePeriod": {
          "startDate": "2017-10-01T00:00:00Z",
          "endDate": "2018-10-31T00:00:00Z"
        },
        "filters": {
          "resourceGroups": [
            "MYDEVTESTRG"
          ],
          "resources": [
            "/subscriptions/{subscription-id}/resourceGroups/MYDEVTESTRG/providers/Microsoft.Compute/virtualMachines/MYVM2",
            "/subscriptions/{subscription-id}/resourceGroups/MYDEVTESTRG/providers/Microsoft.Compute/virtualMachines/platformcloudplatformGeneric1"
          ],
          "meters": [
            "00000000-0000-0000-0000-000000000000"
          ],
          "tags": {
            "category": [
              "Dev",
              "Prod"
            ],
            "department": [
              "engineering",
              "sales"
            ]
          }
        },
        "currentSpend": {
          "amount": 120.89,
          "unit": "USD"
        },
        "notifications": {
          "Actual_GreaterThan_40_Percent": {
            "enabled": true,
            "operator": "GreaterThan",
            "threshold": 40,
            "contactEmails": [
              "johndoe@contoso.com",
              "janesmith@contoso.com"
            ],
            "contactRoles": [
              "Contributor",
              "Reader"
            ]
          },
          "Actual_GreaterThanOrEqualTo_60_Percent": {
            "enabled": true,
            "operator": "GreaterThanOrEqualTo",
            "threshold": 60,
            "contactEmails": [
              "johndoe@contoso.com",
              "janesmith@contoso.com"
            ],
            "contactRoles": [
              "Contributor",
              "Reader"
            ],
            "contactGroups": [
              "/subscriptions/{subscription-id}/resourceGroups/MYDEVTESTRG/providers/microsoft.insights/actionGroups/SampleActionGroup"
            ]
          }
        }
      }
    }
  ]
}

Definitions

Budget

A budget resource.

BudgetsListResult

Result of listing budgets. It contains a list of available budgets in the scope provided.

BudgetTimePeriod

The start and end date for a budget.

CategoryType

The category of the budget, whether the budget tracks cost or usage.

CurrentSpend

The current amount of cost which is being tracked for a budget.

ErrorDetails

The details of the error.

ErrorResponse

Error response indicates that the service is not able to process the incoming request. The reason is provided in the error message.

Filters

May be used to filter budgets by resource group, resource, or meter.

Notification

The notification associated with a budget.

OperatorType

The comparison operator.

TimeGrainType

The time covered by a budget. Tracking of the amount will be reset based on the time grain.

Budget

A budget resource.

Name Type Description
eTag
  • string

eTag of the resource. To handle concurrent update scenario, this field will be used to determine whether the user is updating the latest version or not.

id
  • string

Resource Id.

name
  • string

Resource name.

properties.amount
  • number

The total amount of cost to track with the budget

properties.category

The category of the budget, whether the budget tracks cost or usage.

properties.currentSpend

The current amount of cost which is being tracked for a budget.

properties.filters

May be used to filter budgets by resource group, resource, or meter.

properties.notifications

Dictionary of notifications associated with the budget. Budget can have up to five notifications.

properties.timeGrain

The time covered by a budget. Tracking of the amount will be reset based on the time grain.

properties.timePeriod

Has start and end date of the budget. The start date must be first of the month and should be less than the end date. Budget start date must be on or after June 1, 2017. Future start date should not be more than three months. Past start date should be selected within the timegrain period. There are no restrictions on the end date.

type
  • string

Resource type.

BudgetsListResult

Result of listing budgets. It contains a list of available budgets in the scope provided.

Name Type Description
nextLink
  • string

The link (url) to the next page of results.

value

The list of budgets.

BudgetTimePeriod

The start and end date for a budget.

Name Type Description
endDate
  • string

The end date for the budget. If not provided, we default this to 10 years from the start date.

startDate
  • string

The start date for the budget.

CategoryType

The category of the budget, whether the budget tracks cost or usage.

Name Type Description
Cost
  • string
Usage
  • string

CurrentSpend

The current amount of cost which is being tracked for a budget.

Name Type Description
amount
  • number

The total amount of cost which is being tracked by the budget.

unit
  • string

The unit of measure for the budget amount.

ErrorDetails

The details of the error.

Name Type Description
code
  • string

Error code.

message
  • string

Error message indicating why the operation failed.

ErrorResponse

Error response indicates that the service is not able to process the incoming request. The reason is provided in the error message.

Name Type Description
error

The details of the error.

Filters

May be used to filter budgets by resource group, resource, or meter.

Name Type Description
meters
  • string[]

The list of filters on meters (GUID), mandatory for budgets of usage category.

resourceGroups
  • string[]

The list of filters on resource groups, allowed at subscription level only.

resources
  • string[]

The list of filters on resources.

tags
  • object

The dictionary of filters on tags.

Notification

The notification associated with a budget.

Name Type Description
contactEmails
  • string[]

Email addresses to send the budget notification to when the threshold is exceeded.

contactGroups
  • string[]

Action groups to send the budget notification to when the threshold is exceeded.

contactRoles
  • string[]

Contact roles to send the budget notification to when the threshold is exceeded.

enabled
  • boolean

The notification is enabled or not.

operator

The comparison operator.

threshold
  • number

Threshold value associated with a notification. Notification is sent when the cost exceeded the threshold. It is always percent and has to be between 0 and 1000.

OperatorType

The comparison operator.

Name Type Description
EqualTo
  • string
GreaterThan
  • string
GreaterThanOrEqualTo
  • string

TimeGrainType

The time covered by a budget. Tracking of the amount will be reset based on the time grain.

Name Type Description
Annually
  • string
BillingAnnual
  • string
BillingMonth
  • string
BillingQuarter
  • string
Monthly
  • string
Quarterly
  • string