Share via

Budgets - Get

  • Reference
Service:
Cost Management
API Version:
2023-11-01

Gets the budget for the scope by budget name.

GET https://management.azure.com/{scope}/providers/Microsoft.CostManagement/budgets/{budgetName}?api-version=2023-11-01

URI Parameters

Name In Required Type Description
budgetName
 path True

string

Budget Name.

Regex pattern: ^[a-zA-Z0-9_-]+$
scope
 path True

string

The scope associated with budget operations.

Supported scopes for CategoryType: Cost

Azure RBAC Scopes:

  • '/subscriptions/{subscriptionId}/' for subscription scope
  • '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}' for resourceGroup scope
  • '/providers/Microsoft.Management/managementGroups/{managementGroupId}' for Management Group scope

EA (Enterprise Agreement) Scopes:

  • '/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

MCA (Modern Customer Agreement) Scopes:

  • '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}' for Billing Account scope
  • '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/billingProfiles/{billingProfileId}' for billingProfile scope
  • '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/billingProfiles/{billingProfileId}/invoiceSections/{invoiceSectionId}' for invoiceSection scope
  • '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/customers/{customerId}' for customer scope (CSP only)

Supported scopes for CategoryType: ReservationUtilization

EA (Enterprise Agreement) Scopes:

  • '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}' for Billing Account Scope

MCA (Modern Customer Agreement) Scopes:

  • '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/billingProfiles/{billingProfileId}' for billingProfile scope (non-CSP only)
  • '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/customers/{customerId}' for customer scope (CSP only)
api-version
 query True

string

The API version to use for this operation.

Responses

Name Type Description
200 OK

Budget

OK. The request has succeeded.
Other Status Codes

ErrorResponse

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

Get-Cost-Budget
Get-ReservationUtilization-AlertRule

Get-Cost-Budget

Sample request

GET https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/budgets/TestBudget?api-version=2023-11-01

Sample response

Status code:
200 
{
  "id": "subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/Microsoft.CostManagement/budgets/TestBudget",
  "name": "TestBudget",
  "type": "Microsoft.CostManagement/budgets",
  "eTag": "\"1d34d012214157f\"",
  "properties": {
    "category": "Cost",
    "amount": 100.65,
    "timeGrain": "Monthly",
    "timePeriod": {
      "startDate": "2023-04-01T00:00:00Z",
      "endDate": "2024-10-31T00:00:00Z"
    },
    "filter": {
      "and": [
        {
          "dimensions": {
            "name": "ResourceId",
            "operator": "In",
            "values": [
              "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/Microsoft.Compute/virtualMachines/MSVM2",
              "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/Microsoft.Compute/virtualMachines/platformcloudplatformGeneric1"
            ]
          }
        },
        {
          "tags": {
            "name": "category",
            "operator": "In",
            "values": [
              "Dev",
              "Prod"
            ]
          }
        },
        {
          "tags": {
            "name": "department",
            "operator": "In",
            "values": [
              "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"
        ],
        "contactGroups": [
          "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/MYDEVTESTRG/providers/microsoft.insights/actionGroups/SampleActionGroup"
        ],
        "thresholdType": "Actual"
      }
    }
  }
}

Get-ReservationUtilization-AlertRule

Sample request

GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee:ffffffff-gggg-hhhh-iiii-jjjjjjjjjjjj_2023-04-01/billingProfiles/KKKK-LLLL-MMM-NNN/providers/Microsoft.CostManagement/budgets/TestAlertRule?api-version=2023-11-01

Sample response

Status code:
200 
{
  "id": "providers/Microsoft.Billing/billingAccounts/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee:ffffffff-gggg-hhhh-iiii-jjjjjjjjjjjj_2023-04-01/billingProfiles/KKKK-LLLL-MMM-NNN/providers/Microsoft.CostManagement/budgets/TestAlertRule",
  "name": "TestAlertRule",
  "type": "Microsoft.CostManagement/budgets",
  "eTag": "\"1d34d012214157f\"",
  "properties": {
    "category": "ReservationUtilization",
    "timeGrain": "Last30Days",
    "timePeriod": {
      "startDate": "2023-04-01T00:00:00Z",
      "endDate": "2025-04-01T00:00:00Z"
    },
    "filter": {
      "dimensions": {
        "name": "ReservedResourceType",
        "operator": "In",
        "values": [
          "VirtualMachines",
          "SqlDatabases",
          "CosmosDb"
        ]
      }
    },
    "notifications": {
      "Actual_LessThan_99_Percent": {
        "enabled": true,
        "operator": "LessThan",
        "threshold": 99,
        "frequency": "Daily",
        "locale": "en-us",
        "contactEmails": [
          "johndoe@contoso.com",
          "janesmith@contoso.com"
        ]
      }
    }
  }
}

Definitions

Name Description
Budget

A budget resource.
BudgetComparisonExpression

The comparison expression to be used in the budgets.
BudgetFilter

May be used to filter budgets by user-specified dimensions and/or tags.

Supported for CategoryType(s): Cost, ReservationUtilization.
BudgetFilterProperties

The Dimensions or Tags to filter a budget by.

Supported for CategoryType(s): Cost, ReservationUtilization.
BudgetNotificationOperatorType

The comparison operator.

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported operators for CategoryType: Cost

  • GreaterThan
  • GreaterThanOrEqualTo

Supported operators for CategoryType: ReservationUtilization

  • LessThan
BudgetOperatorType

The operator to use for comparison.
BudgetTimePeriod

The time period that defines the active period of the budget. The budget will evaluate data on or after the startDate and will expire on the endDate.

Supported for CategoryType(s): Cost, ReservationUtilization.

Required for CategoryType(s): Cost, ReservationUtilization.
CategoryType

The category of the budget.

  • 'Cost' defines a Budget.
  • 'ReservationUtilization' defines a Reservation Utilization Alert Rule.
CultureCode

Language in which the recipient will receive the notification,

Supported for CategoryType(s): Cost, ReservationUtilization.
CurrentSpend

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

Supported for CategoryType(s): Cost.
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.

Some Error responses:

  • 429 TooManyRequests - Request is throttled. Retry after waiting for the time specified in the "x-ms-ratelimit-microsoft.consumption-retry-after" header.

  • 503 ServiceUnavailable - Service is temporarily unavailable. Retry after waiting for the time specified in the "Retry-After" header.
ForecastSpend

The forecasted cost which is being tracked for a budget.

Supported for CategoryType(s): Cost.
Frequency

Frequency of a notification. Represents how long the notification will be silent after triggering an alert for a threshold breach. If not specified, the frequency will be set by default based on the timeGrain (Weekly when timeGrain: Last7Days, Monthly when timeGrain: Last30Days).

Supported for CategoryType(s): ReservationUtilization.
Notification

The notification associated with a budget.

Supported for CategoryType(s): Cost, ReservationUtilization.
ThresholdType

The type of threshold.

Supported for CategoryType(s): Cost.
TimeGrainType

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

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported timeGrainTypes for CategoryType: Cost

  • Monthly

  • Quarterly

  • Annually

  • BillingMonth*

  • BillingQuarter*

  • BillingAnnual*

    *only supported for Web Direct customers.

Supported timeGrainTypes for CategoryType: ReservationUtilization

  • Last7Days
  • Last30Days

Required for CategoryType(s): Cost, ReservationUtilization.

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.

Supported for CategoryType(s): Cost.

Required for CategoryType(s): Cost.
properties.category

CategoryType

The category of the budget.

  • 'Cost' defines a Budget.
  • 'ReservationUtilization' defines a Reservation Utilization Alert Rule.
properties.currentSpend

CurrentSpend

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

Supported for CategoryType(s): Cost.
properties.filter

BudgetFilter

May be used to filter budgets by user-specified dimensions and/or tags.

Supported for CategoryType(s): Cost, ReservationUtilization.
properties.forecastSpend

ForecastSpend

The forecasted cost which is being tracked for a budget.

Supported for CategoryType(s): Cost.
properties.notifications

<string,  Notification>

Dictionary of notifications associated with the budget.

Supported for CategoryType(s): Cost, ReservationUtilization.

  • Constraints for CategoryType: Cost - Budget can have up to 5 notifications with thresholdType: Actual and 5 notifications with thresholdType: Forecasted.
  • Constraints for CategoryType: ReservationUtilization - Only one notification allowed. thresholdType is not applicable.
properties.timeGrain

TimeGrainType

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

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported timeGrainTypes for CategoryType: Cost

  • Monthly

  • Quarterly

  • Annually

  • BillingMonth*

  • BillingQuarter*

  • BillingAnnual*

    *only supported for Web Direct customers.

Supported timeGrainTypes for CategoryType: ReservationUtilization

  • Last7Days
  • Last30Days

Required for CategoryType(s): Cost, ReservationUtilization.
properties.timePeriod

BudgetTimePeriod

The time period that defines the active period of the budget. The budget will evaluate data on or after the startDate and will expire on the endDate.

Supported for CategoryType(s): Cost, ReservationUtilization.

Required for CategoryType(s): Cost, ReservationUtilization.
type

string

Resource type.

BudgetComparisonExpression

The comparison expression to be used in the budgets.

Name Type Description
name

string

The name of the column to use in comparison.
operator

BudgetOperatorType

The operator to use for comparison.
values

string[]

Array of values to use for comparison

BudgetFilter

May be used to filter budgets by user-specified dimensions and/or tags.

Supported for CategoryType(s): Cost, ReservationUtilization.

Name Type Description
and

BudgetFilterProperties[]

The logical "AND" expression. Must have at least 2 items.

Supported for CategoryType(s): Cost.
dimensions

BudgetComparisonExpression

Has comparison expression for a dimension.

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported dimension names for CategoryType: ReservationUtilization

  • ReservationId
  • ReservedResourceType
tags

BudgetComparisonExpression

Has comparison expression for a tag.

Supported for CategoryType(s): Cost.

BudgetFilterProperties

The Dimensions or Tags to filter a budget by.

Supported for CategoryType(s): Cost, ReservationUtilization.

Name Type Description
dimensions

BudgetComparisonExpression

Has comparison expression for a dimension.

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported dimension names for CategoryType: ReservationUtilization

  • ReservationId
  • ReservedResourceType
tags

BudgetComparisonExpression

Has comparison expression for a tag.

Supported for CategoryType(s): Cost.

BudgetNotificationOperatorType

The comparison operator.

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported operators for CategoryType: Cost

  • GreaterThan
  • GreaterThanOrEqualTo

Supported operators for CategoryType: ReservationUtilization

  • LessThan
Name Type Description
EqualTo

string

Notification will be triggered if the evaluated cost is the same as threshold value. Note: It’s not recommended to use this OperatorType as there’s low chance of cost being exactly the same as threshold value, leading to missing of your alert. This OperatorType will be deprecated in future.

Supported for CategoryType(s): Cost.
GreaterThan

string

Notification will be triggered if the evaluated cost is greater than the threshold value. Note: This is the recommended OperatorType while configuring Budget Alert.

Supported for CategoryType(s): Cost.
GreaterThanOrEqualTo

string

Notification will be triggered if the evaluated cost is greater than or equal to the threshold value.

Supported for CategoryType(s): Cost.
LessThan

string

Notification will be triggered if any Reservations in the scope of the Reservation Utilization Alert Rule have a utilization less than the threshold percentage.

Supported for CategoryType(s): ReservationUtilization.

BudgetOperatorType

The operator to use for comparison.

Name Type Description
In

string

BudgetTimePeriod

The time period that defines the active period of the budget. The budget will evaluate data on or after the startDate and will expire on the endDate.

Supported for CategoryType(s): Cost, ReservationUtilization.

Required for CategoryType(s): Cost, ReservationUtilization.

Name Type Description
endDate

string

The end date for the budget.

  • Constraints for CategoryType: Cost - No constraints. If not provided, we default this to 10 years from the start date.

  • Constraints for CategoryType: ReservationUtilization - End date cannot be more than 3 years after the start date.
startDate

string

The start date for the budget.

  • Constraints for CategoryType: Cost - 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 twelve months. Past start date should be selected within the timegrain period.

  • Constraints for CategoryType: ReservationUtilization - Must be on or after the current date and less than the end date.

CategoryType

The category of the budget.

  • 'Cost' defines a Budget.
  • 'ReservationUtilization' defines a Reservation Utilization Alert Rule.
Name Type Description
Cost

string

A Budget that evaluates monetary cost of Azure resources against an amount, and alerts based on a configured notification threshold.
ReservationUtilization

string

An Alert Rule that evaluates the utilization percentage of Azure Reservations, and alerts based on a configured notification threshold.

CultureCode

Language in which the recipient will receive the notification,

Supported for CategoryType(s): Cost, ReservationUtilization.

Name Type Description
cs-cz

string

da-dk

string

de-de

string

en-gb

string

en-us

string

es-es

string

fr-fr

string

hu-hu

string

it-it

string

ja-jp

string

ko-kr

string

nb-no

string

nl-nl

string

pl-pl

string

pt-br

string

pt-pt

string

ru-ru

string

sv-se

string

tr-tr

string

zh-cn

string

zh-tw

string

CurrentSpend

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

Supported for CategoryType(s): Cost.

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.

Some Error responses:

  • 429 TooManyRequests - Request is throttled. Retry after waiting for the time specified in the "x-ms-ratelimit-microsoft.consumption-retry-after" header.

  • 503 ServiceUnavailable - Service is temporarily unavailable. Retry after waiting for the time specified in the "Retry-After" header.

Name Type Description
error

ErrorDetails

The details of the error.

ForecastSpend

The forecasted cost which is being tracked for a budget.

Supported for CategoryType(s): Cost.

Name Type Description
amount

number

The forecasted cost for the total time period which is being tracked by the budget. This value is only provided if the budget contains a forecast alert type.
unit

string

The unit of measure for the budget amount.

Frequency

Frequency of a notification. Represents how long the notification will be silent after triggering an alert for a threshold breach. If not specified, the frequency will be set by default based on the timeGrain (Weekly when timeGrain: Last7Days, Monthly when timeGrain: Last30Days).

Supported for CategoryType(s): ReservationUtilization.

Name Type Description
Daily

string

After the threshold breaches and an Alert is fired, no further alerts will be sent until the next calendar day.
Monthly

string

After the threshold breaches and an Alert is fired, no further alerts will be sent for 30 calendar days.
Weekly

string

After the threshold breaches and an Alert is fired, no further alerts will be sent for 7 calendar days.

Notification

The notification associated with a budget.

Supported for CategoryType(s): Cost, ReservationUtilization.

Name Type Default value Description
contactEmails

string[]

Email addresses to send the notification to when the threshold is breached. Must have at least one contact email or contact group specified at the Subscription or Resource Group scopes. All other scopes must have at least one contact email specified.

Supported for CategoryType(s): Cost, ReservationUtilization.
contactGroups

string[]

Subscription or Resource Group scopes only. Action groups to send the notification to when the threshold is exceeded. Must be provided as a fully qualified Azure resource id.

Supported for CategoryType(s): Cost.
contactRoles

string[]

Subscription or Resource Group scopes only. Contact roles to send the notification to when the threshold is breached.

Supported for CategoryType(s): Cost.
enabled

boolean

The notification is enabled or not.

Supported for CategoryType(s): Cost, ReservationUtilization.
frequency

Frequency

Frequency of a notification. Represents how long the notification will be silent after triggering an alert for a threshold breach. If not specified, the frequency will be set by default based on the timeGrain (Weekly when timeGrain: Last7Days, Monthly when timeGrain: Last30Days).

Supported for CategoryType(s): ReservationUtilization.
locale

CultureCode

Language in which the recipient will receive the notification,

Supported for CategoryType(s): Cost, ReservationUtilization.
operator

BudgetNotificationOperatorType

The comparison operator.

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported operators for CategoryType: Cost

  • GreaterThan
  • GreaterThanOrEqualTo

Supported operators for CategoryType: ReservationUtilization

  • LessThan
threshold

number

Threshold value associated with a notification. It is always percent with a maximum of 2 decimal places.

Supported for CategoryType(s): Cost, ReservationUtilization.

CategoryType: Cost - Must be between 0 and 1000. Notification is sent when the cost exceeded the threshold.

CategoryType: ReservationUtilization - Must be between 0 and 100. Notification is sent when a reservation has a utilization percentage below the threshold.
thresholdType

ThresholdType

Actual

The type of threshold.

Supported for CategoryType(s): Cost.

ThresholdType

The type of threshold.

Supported for CategoryType(s): Cost.

Name Type Description
Actual

string

Actual costs budget alerts notify when the actual accrued cost exceeds the allocated budget.
Forecasted

string

Forecasted costs budget alerts provide advanced notification that your spending trends are likely to exceed your allocated budget, as it relies on forecasted cost predictions.

TimeGrainType

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

Supported for CategoryType(s): Cost, ReservationUtilization.

Supported timeGrainTypes for CategoryType: Cost

  • Monthly

  • Quarterly

  • Annually

  • BillingMonth*

  • BillingQuarter*

  • BillingAnnual*

    *only supported for Web Direct customers.

Supported timeGrainTypes for CategoryType: ReservationUtilization

  • Last7Days
  • Last30Days

Required for CategoryType(s): Cost, ReservationUtilization.

Name Type Description
Annually

string

The budget will track costs in the current calendar year against the amount.

Supported for CategoryType: Cost only.
BillingAnnual

string

The budget will track costs in the current billing year against the amount.

Supported for CategoryType: Cost and Web Direct customers only.
BillingMonth

string

The budget will track costs in the current billing month against the amount.

Supported for CategoryType: Cost and Web Direct customers only.
BillingQuarter

string

The budget will track costs in the current billing quarter against the amount.

Supported for CategoryType: Cost and Web Direct customers only.
Last30Days

string

The Reservation Utilization Alert Rule will evaluate reservations based on their 30-Day utilization percentage.

Supported for CategoryType: ReservationUtilization only.
Last7Days

string

The Reservation Utilization Alert Rule will evaluate reservations based on their 7-Day utilization percentage.

Supported for CategoryType: ReservationUtilization only.
Monthly

string

The budget will track costs in the current calendar month against the amount.

Supported for CategoryType: Cost only.
Quarterly

string

The budget will track costs in the current calendar quarter against the amount.

Supported for CategoryType: Cost only.