Forecast - Usage
Lists the forecast charges for scope defined.
POST https://management.azure.com/{scope}/providers/Microsoft.CostManagement/forecast?api-version=2024-08-01
POST https://management.azure.com/{scope}/providers/Microsoft.CostManagement/forecast?$filter={$filter}&api-version=2024-08-01
URI Parameters
Name | In | Required | Type | Description |
---|---|---|---|---|
scope
|
path | True |
string |
The scope associated with forecast operations. This includes '/subscriptions/{subscriptionId}/' for subscription scope, '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}' for resourceGroup scope, '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}' for Billing Account scope and '/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}/billingProfiles/{billingProfileId}/invoiceSections/{invoiceSectionId}' for invoiceSection scope, and '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/customers/{customerId}' specific for partners. |
api-version
|
query | True |
string |
The API version to use for this operation. |
$filter
|
query |
string |
May be used to filter forecasts by properties/usageDate (Utc time), properties/chargeType or properties/grain. The filter supports 'eq', 'lt', 'gt', 'le', 'ge', and 'and'. It does not currently support 'ne', 'or', or 'not'. |
Request Body
Name | Required | Type | Description |
---|---|---|---|
dataset | True |
Has definition for data in this forecast. |
|
timeframe | True |
The time frame for pulling data for the forecast. If custom, then a specific time period must be provided. |
|
type | True |
The type of the forecast. |
|
includeActualCost |
boolean |
A boolean determining if actualCost will be included. |
|
includeFreshPartialCost |
boolean |
A boolean determining if FreshPartialCost will be included. |
|
timePeriod |
Has time period for pulling data for the forecast. |
Responses
Name | Type | Description |
---|---|---|
200 OK |
OK. The request has succeeded. |
|
204 No Content |
No Content. Resource is not available. |
|
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
Billing |
Billing |
Department |
Enrollment |
Invoice |
Resource |
Subscription |
BillingAccountForecast
Sample request
POST https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:6789/providers/Microsoft.CostManagement/forecast?api-version=2024-08-01
{
"type": "Usage",
"timeframe": "Custom",
"timePeriod": {
"from": "2022-08-01T00:00:00+00:00",
"to": "2022-08-31T23:59:59+00:00"
},
"dataset": {
"granularity": "Daily",
"aggregation": {
"totalCost": {
"name": "Cost",
"function": "Sum"
}
},
"filter": {
"and": [
{
"or": [
{
"dimensions": {
"name": "ResourceLocation",
"operator": "In",
"values": [
"East US",
"West Europe"
]
}
},
{
"tags": {
"name": "Environment",
"operator": "In",
"values": [
"UAT",
"Prod"
]
}
}
]
},
{
"dimensions": {
"name": "ResourceGroup",
"operator": "In",
"values": [
"API"
]
}
}
]
}
},
"includeActualCost": false,
"includeFreshPartialCost": false
}
Sample response
{
"id": "providers/Microsoft.Billing/billingAccounts/12345:6789/providers/Microsoft.CostManagement/query/ad67fd91-c131-4bda-9ba9-7187ecb1cebd",
"name": "ad67fd91-c131-4bda-9ba9-7187ecb1cebd",
"type": "Microsoft.CostManagement/query",
"properties": {
"nextLink": "https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:6789/providers/Microsoft.CostManagement/Forecast?api-version=2021-10-01&$skiptoken=AQAAAA%3D%3D",
"columns": [
{
"name": "PreTaxCost",
"type": "Number"
},
{
"name": "UsageDate",
"type": "Number"
},
{
"name": "CostStatus",
"type": "String"
},
{
"name": "Currency",
"type": "String"
}
],
"rows": [
[
2.10333307059661,
20180331,
"Forecast",
"USD"
],
[
218.68795741935486,
20180331,
"Forecast",
"USD"
],
[
0.14384913581657052,
20180401,
"Forecast",
"USD"
],
[
0.009865586851323632,
20180429,
"Forecast",
"USD"
]
]
}
}
BillingProfileForecast
Sample request
POST https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:6789/billingProfiles/13579/providers/Microsoft.CostManagement/forecast?api-version=2024-08-01
{
"type": "Usage",
"timeframe": "Custom",
"timePeriod": {
"from": "2022-08-01T00:00:00+00:00",
"to": "2022-08-31T23:59:59+00:00"
},
"dataset": {
"granularity": "Daily",
"aggregation": {
"totalCost": {
"name": "Cost",
"function": "Sum"
}
},
"filter": {
"and": [
{
"or": [
{
"dimensions": {
"name": "ResourceLocation",
"operator": "In",
"values": [
"East US",
"West Europe"
]
}
},
{
"tags": {
"name": "Environment",
"operator": "In",
"values": [
"UAT",
"Prod"
]
}
}
]
},
{
"dimensions": {
"name": "ResourceGroup",
"operator": "In",
"values": [
"API"
]
}
}
]
}
},
"includeActualCost": false,
"includeFreshPartialCost": false
}
Sample response
{
"id": "providers/Microsoft.Billing/billingAccounts/12345:6789/billingProfiles/13579/providers/Microsoft.CostManagement/query/ad67fd91-c131-4bda-9ba9-7187ecb1cebd",
"name": "ad67fd91-c131-4bda-9ba9-7187ecb1cebd",
"type": "Microsoft.CostManagement/query",
"properties": {
"nextLink": "https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:6789/billingProfiles/13579/providers/Microsoft.CostManagement/Forecast?api-version=2019-10-01&$skiptoken=AQAAAA%3D%3D",
"columns": [
{
"name": "PreTaxCost",
"type": "Number"
},
{
"name": "UsageDate",
"type": "Number"
},
{
"name": "CostStatus",
"type": "String"
},
{
"name": "Currency",
"type": "String"
}
],
"rows": [
[
2.10333307059661,
20180331,
"Forecast",
"USD"
],
[
218.68795741935486,
20180331,
"Forecast",
"USD"
],
[
0.14384913581657052,
20180401,
"Forecast",
"USD"
],
[
0.009865586851323632,
20180429,
"Forecast",
"USD"
]
]
}
}
DepartmentForecast
Sample request
POST https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:6789/departments/123/providers/Microsoft.CostManagement/forecast?api-version=2024-08-01
{
"type": "Usage",
"timeframe": "Custom",
"timePeriod": {
"from": "2022-08-01T00:00:00+00:00",
"to": "2022-08-31T23:59:59+00:00"
},
"dataset": {
"granularity": "Daily",
"aggregation": {
"totalCost": {
"name": "Cost",
"function": "Sum"
}
},
"filter": {
"and": [
{
"or": [
{
"dimensions": {
"name": "ResourceLocation",
"operator": "In",
"values": [
"East US",
"West Europe"
]
}
},
{
"tags": {
"name": "Environment",
"operator": "In",
"values": [
"UAT",
"Prod"
]
}
}
]
},
{
"dimensions": {
"name": "ResourceGroup",
"operator": "In",
"values": [
"API"
]
}
}
]
}
},
"includeActualCost": false,
"includeFreshPartialCost": false
}
Sample response
{
"id": "providers/Microsoft.Billing/billingAccounts/12345:6789/departments/123/providers/Microsoft.CostManagement/query/ad67fd91-c131-4bda-9ba9-7187ecb1cebd",
"name": "ad67fd91-c131-4bda-9ba9-7187ecb1cebd",
"type": "Microsoft.CostManagement/query",
"properties": {
"nextLink": "https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:6789/departments/123/providers/Microsoft.CostManagement/Forecast?api-version=2021-10-01&$skiptoken=AQAAAA%3D%3D",
"columns": [
{
"name": "PreTaxCost",
"type": "Number"
},
{
"name": "UsageDate",
"type": "Number"
},
{
"name": "CostStatus",
"type": "String"
},
{
"name": "Currency",
"type": "String"
}
],
"rows": [
[
2.10333307059661,
20180331,
"Forecast",
"USD"
],
[
218.68795741935486,
20180331,
"Forecast",
"USD"
],
[
0.14384913581657052,
20180401,
"Forecast",
"USD"
],
[
0.009865586851323632,
20180429,
"Forecast",
"USD"
]
]
}
}
EnrollmentAccountForecast
Sample request
POST https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:6789/enrollmentAccounts/456/providers/Microsoft.CostManagement/forecast?api-version=2024-08-01
{
"type": "Usage",
"timeframe": "Custom",
"timePeriod": {
"from": "2022-08-01T00:00:00+00:00",
"to": "2022-08-31T23:59:59+00:00"
},
"dataset": {
"granularity": "Daily",
"aggregation": {
"totalCost": {
"name": "Cost",
"function": "Sum"
}
},
"filter": {
"and": [
{
"or": [
{
"dimensions": {
"name": "ResourceLocation",
"operator": "In",
"values": [
"East US",
"West Europe"
]
}
},
{
"tags": {
"name": "Environment",
"operator": "In",
"values": [
"UAT",
"Prod"
]
}
}
]
},
{
"dimensions": {
"name": "ResourceGroup",
"operator": "In",
"values": [
"API"
]
}
}
]
}
},
"includeActualCost": false,
"includeFreshPartialCost": false
}
Sample response
{
"id": "providers/Microsoft.Billing/billingAccounts/12345:6789/enrollmentAccounts/456/providers/Microsoft.CostManagement/query/ad67fd91-c131-4bda-9ba9-7187ecb1cebd",
"name": "ad67fd91-c131-4bda-9ba9-7187ecb1cebd",
"type": "Microsoft.CostManagement/query",
"properties": {
"nextLink": "https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:6789/enrollmentAccounts/456/providers/Microsoft.CostManagement/Forecast?api-version=2021-10-01&$skiptoken=AQAAAA%3D%3D",
"columns": [
{
"name": "PreTaxCost",
"type": "Number"
},
{
"name": "UsageDate",
"type": "Number"
},
{
"name": "CostStatus",
"type": "String"
},
{
"name": "Currency",
"type": "String"
}
],
"rows": [
[
2.10333307059661,
20180331,
"Forecast",
"USD"
],
[
218.68795741935486,
20180331,
"Forecast",
"USD"
],
[
0.14384913581657052,
20180401,
"Forecast",
"USD"
],
[
0.009865586851323632,
20180429,
"Forecast",
"USD"
]
]
}
}
InvoiceSectionForecast
Sample request
POST https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:6789/billingProfiles/13579/invoiceSections/9876/providers/Microsoft.CostManagement/forecast?api-version=2024-08-01
{
"type": "Usage",
"timeframe": "Custom",
"timePeriod": {
"from": "2022-08-01T00:00:00+00:00",
"to": "2022-08-31T23:59:59+00:00"
},
"dataset": {
"granularity": "Daily",
"aggregation": {
"totalCost": {
"name": "Cost",
"function": "Sum"
}
},
"filter": {
"and": [
{
"or": [
{
"dimensions": {
"name": "ResourceLocation",
"operator": "In",
"values": [
"East US",
"West Europe"
]
}
},
{
"tags": {
"name": "Environment",
"operator": "In",
"values": [
"UAT",
"Prod"
]
}
}
]
},
{
"dimensions": {
"name": "ResourceGroup",
"operator": "In",
"values": [
"API"
]
}
}
]
}
},
"includeActualCost": false,
"includeFreshPartialCost": false
}
Sample response
{
"id": "providers/Microsoft.Billing/billingAccounts/12345:6789/billingProfiles/13579/invoiceSections/9876/providers/Microsoft.CostManagement/query/ad67fd91-c131-4bda-9ba9-7187ecb1cebd",
"name": "ad67fd91-c131-4bda-9ba9-7187ecb1cebd",
"type": "Microsoft.CostManagement/query",
"properties": {
"nextLink": "https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:6789/billingProfiles/13579/invoiceSections/9876/providers/Microsoft.CostManagement/Forecast?api-version=2019-10-01&$skiptoken=AQAAAA%3D%3D",
"columns": [
{
"name": "PreTaxCost",
"type": "Number"
},
{
"name": "UsageDate",
"type": "Number"
},
{
"name": "CostStatus",
"type": "String"
},
{
"name": "Currency",
"type": "String"
}
],
"rows": [
[
2.10333307059661,
20180331,
"Forecast",
"USD"
],
[
218.68795741935486,
20180331,
"Forecast",
"USD"
],
[
0.14384913581657052,
20180401,
"Forecast",
"USD"
],
[
0.009865586851323632,
20180429,
"Forecast",
"USD"
]
]
}
}
ResourceGroupForecast
Sample request
POST https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/ScreenSharingTest-peer/providers/Microsoft.CostManagement/forecast?api-version=2024-08-01
{
"type": "Usage",
"timeframe": "Custom",
"timePeriod": {
"from": "2022-08-01T00:00:00+00:00",
"to": "2022-08-31T23:59:59+00:00"
},
"dataset": {
"granularity": "Daily",
"aggregation": {
"totalCost": {
"name": "Cost",
"function": "Sum"
}
},
"filter": {
"and": [
{
"or": [
{
"dimensions": {
"name": "ResourceLocation",
"operator": "In",
"values": [
"East US",
"West Europe"
]
}
},
{
"tags": {
"name": "Environment",
"operator": "In",
"values": [
"UAT",
"Prod"
]
}
}
]
},
{
"dimensions": {
"name": "ResourceGroup",
"operator": "In",
"values": [
"API"
]
}
}
]
}
},
"includeActualCost": false,
"includeFreshPartialCost": false
}
Sample response
{
"id": "subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/ScreenSharingTest-peer/providers/Microsoft.CostManagement/query/00000000-0000-0000-0000-000000000000",
"name": "55312978-ba1b-415c-9304-cfd9c43c0481",
"type": "Microsoft.CostManagement/query",
"properties": {
"nextLink": null,
"columns": [
{
"name": "PreTaxCost",
"type": "Number"
},
{
"name": "UsageDate",
"type": "Number"
},
{
"name": "CostStatus",
"type": "String"
},
{
"name": "Currency",
"type": "String"
}
],
"rows": [
[
2.10333307059661,
20180331,
"Forecast",
"USD"
]
]
}
}
SubscriptionForecast
Sample request
POST https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/forecast?api-version=2024-08-01
{
"type": "Usage",
"timeframe": "Custom",
"timePeriod": {
"from": "2022-08-01T00:00:00+00:00",
"to": "2022-08-31T23:59:59+00:00"
},
"dataset": {
"granularity": "Daily",
"aggregation": {
"totalCost": {
"name": "Cost",
"function": "Sum"
}
},
"filter": {
"and": [
{
"or": [
{
"dimensions": {
"name": "ResourceLocation",
"operator": "In",
"values": [
"East US",
"West Europe"
]
}
},
{
"tags": {
"name": "Environment",
"operator": "In",
"values": [
"UAT",
"Prod"
]
}
}
]
},
{
"dimensions": {
"name": "ResourceGroup",
"operator": "In",
"values": [
"API"
]
}
}
]
}
},
"includeActualCost": false,
"includeFreshPartialCost": false
}
Sample response
{
"id": "subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/query/00000000-0000-0000-0000-000000000000",
"name": "55312978-ba1b-415c-9304-cfd9c43c0481",
"type": "Microsoft.CostManagement/query",
"properties": {
"nextLink": null,
"columns": [
{
"name": "PreTaxCost",
"type": "Number"
},
{
"name": "UsageDate",
"type": "Number"
},
{
"name": "CostStatus",
"type": "String"
},
{
"name": "Currency",
"type": "String"
}
],
"rows": [
[
2.10333307059661,
20180331,
"Forecast",
"USD"
],
[
218.68795741935486,
20180331,
"Forecast",
"USD"
],
[
0.14384913581657052,
20180401,
"Forecast",
"USD"
],
[
0.009865586851323632,
20180429,
"Forecast",
"USD"
]
]
}
}
Definitions
Name | Description |
---|---|
Error |
The details of the error. |
Error |
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:
|
Forecast |
The aggregation expression to be used in the forecast. |
Forecast |
Forecast column properties |
Forecast |
The comparison expression to be used in the forecast. |
Forecast |
The definition of data present in the forecast. |
Forecast |
The configuration of dataset in the forecast. |
Forecast |
The definition of a forecast. |
Forecast |
The filter expression to be used in the export. |
Forecast |
The operator to use for comparison. |
Forecast |
Result of forecast. It contains all columns listed under groupings and aggregation. |
Forecast |
The time frame for pulling data for the forecast. |
Forecast |
Has time period for pulling data for the forecast. |
Forecast |
The type of the forecast. |
Function |
The name of the column to aggregate. |
Function |
The name of the aggregation function to use. |
Granularity |
The granularity of rows in the forecast. |
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 |
The details of the error. |
ForecastAggregation
The aggregation expression to be used in the forecast.
Name | Type | Description |
---|---|---|
function |
The name of the aggregation function to use. |
|
name |
The name of the column to aggregate. |
ForecastColumn
Forecast column properties
Name | Type | Description |
---|---|---|
name |
string |
The name of column. |
type |
string |
The type of column. |
ForecastComparisonExpression
The comparison expression to be used in the forecast.
Name | Type | Description |
---|---|---|
name |
string |
The name of the column to use in comparison. |
operator |
The operator to use for comparison. |
|
values |
string[] |
Array of values to use for comparison |
ForecastDataset
The definition of data present in the forecast.
Name | Type | Description |
---|---|---|
aggregation |
<string,
Forecast |
Dictionary of aggregation expression to use in the forecast. The key of each item in the dictionary is the alias for the aggregated column. forecast can have up to 2 aggregation clauses. |
configuration |
Has configuration information for the data in the export. The configuration will be ignored if aggregation and grouping are provided. |
|
filter |
Has filter expression to use in the forecast. |
|
granularity |
The granularity of rows in the forecast. |
ForecastDatasetConfiguration
The configuration of dataset in the forecast.
Name | Type | Description |
---|---|---|
columns |
string[] |
Array of column names to be included in the forecast. Any valid forecast column name is allowed. If not provided, then forecast includes all columns. |
ForecastDefinition
The definition of a forecast.
Name | Type | Description |
---|---|---|
dataset |
Has definition for data in this forecast. |
|
includeActualCost |
boolean |
A boolean determining if actualCost will be included. |
includeFreshPartialCost |
boolean |
A boolean determining if FreshPartialCost will be included. |
timePeriod |
Has time period for pulling data for the forecast. |
|
timeframe |
The time frame for pulling data for the forecast. If custom, then a specific time period must be provided. |
|
type |
The type of the forecast. |
ForecastFilter
The filter expression to be used in the export.
Name | Type | Description |
---|---|---|
and |
The logical "AND" expression. Must have at least 2 items. |
|
dimensions |
Has comparison expression for a dimension |
|
or |
The logical "OR" expression. Must have at least 2 items. |
|
tags |
Has comparison expression for a tag |
ForecastOperatorType
The operator to use for comparison.
Name | Type | Description |
---|---|---|
In |
string |
ForecastResult
Result of forecast. It contains all columns listed under groupings and aggregation.
Name | Type | Description |
---|---|---|
eTag |
string |
ETag of the resource. |
id |
string |
Resource Id. |
location |
string |
Location of the resource. |
name |
string |
Resource name. |
properties.columns |
Array of columns |
|
properties.nextLink |
string |
The link (url) to the next page of results. |
properties.rows |
Rows[] |
Array of rows |
sku |
string |
SKU of the resource. |
tags |
object |
Resource tags. |
type |
string |
Resource type. |
ForecastTimeframe
The time frame for pulling data for the forecast.
Name | Type | Description |
---|---|---|
Custom |
string |
ForecastTimePeriod
Has time period for pulling data for the forecast.
Name | Type | Description |
---|---|---|
from |
string |
The start date to pull data from. |
to |
string |
The end date to pull data to. |
ForecastType
The type of the forecast.
Name | Type | Description |
---|---|---|
ActualCost |
string |
|
AmortizedCost |
string |
|
Usage |
string |
FunctionName
The name of the column to aggregate.
Name | Type | Description |
---|---|---|
Cost |
string |
|
CostUSD |
string |
|
PreTaxCost |
string |
|
PreTaxCostUSD |
string |
FunctionType
The name of the aggregation function to use.
Name | Type | Description |
---|---|---|
Sum |
string |
GranularityType
The granularity of rows in the forecast.
Name | Type | Description |
---|---|---|
Daily |
string |