Forecasts - List

Service:: Consumption

API Version:: 2021-05-01

Lists the forecast charges for scope defined. Please note that this API is no longer actively under development. We recommend using our new Forecast API moving forward: https://docs.microsoft.com/en-us/rest/api/cost-management/forecast/usage.

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Consumption/forecasts?api-version=2021-05-01

With optional parameters:

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Consumption/forecasts?$filter={$filter}&api-version=2021-05-01

URI Parameters

Name	In	Required	Type	Description
subscriptionId	path	True	string	Azure Subscription ID.
api-version	query	True	string	Version of the API to be used with the client request. The current version is 2021-05-01.
$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'.

Responses

Name	Type	Description
200 OK	ForecastsListResult	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

ForecastsList

ForecastsListFilterByDates

ForecastsListFilterByGrain

ForecastsList

Sample request

HTTP

GET https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Consumption/forecasts?api-version=2021-05-01

Sample response

Status code:: 200

{
  "value": [
    {
      "id": "/subscriptions/subid/providers/Microsoft.Consumption/forecasts/forecastId1",
      "name": "forecastId1",
      "type": "Microsoft.Consumption/forecasts",
      "properties": {
        "usageDate": "2018-04-01",
        "grain": "Daily",
        "charge": 752,
        "currency": "USD",
        "chargeType": "Actual",
        "confidenceLevels": null
      }
    },
    {
      "id": "/subscriptions/subid/providers/Microsoft.Consumption/forecasts/forecastId2",
      "name": "forecastId2",
      "type": "Microsoft.Consumption/forecasts",
      "properties": {
        "usageDate": "2018-04-02",
        "grain": "Daily",
        "charge": 753.809074,
        "currency": "USD",
        "chargeType": "Forecast",
        "confidenceLevels": [
          {
            "percentage": 95,
            "bound": "Upper",
            "value": 1165.951737
          },
          {
            "percentage": 95,
            "bound": "Lower",
            "value": 340.753404
          }
        ]
      }
    }
  ]
}

ForecastsListFilterByDates

Sample request

HTTP

GET https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Consumption/forecasts?$filter=properties/usagedate ge '2018-04-01' AND properties/usagedate le '2018-04-02'&api-version=2021-05-01

Sample response

Status code:: 200

{
  "value": [
    {
      "id": "/subscriptions/subid/providers/Microsoft.Consumption/forecasts/forecastId1",
      "name": "forecastId1",
      "type": "Microsoft.Consumption/forecasts",
      "properties": {
        "usageDate": "2018-04-01",
        "grain": "Daily",
        "charge": 752,
        "currency": "USD",
        "chargeType": "Actual",
        "confidenceLevels": null
      }
    },
    {
      "id": "/subscriptions/subid/providers/Microsoft.Consumption/forecasts/forecastId2",
      "name": "forecastId2",
      "type": "Microsoft.Consumption/forecasts",
      "properties": {
        "usageDate": "2018-04-02",
        "grain": "Daily",
        "charge": 753.809074,
        "currency": "USD",
        "chargeType": "Forecast",
        "confidenceLevels": [
          {
            "percentage": 95,
            "bound": "Upper",
            "value": 1165.951737
          },
          {
            "percentage": 95,
            "bound": "Lower",
            "value": 340.753404
          }
        ]
      }
    }
  ]
}

ForecastsListFilterByGrain

Sample request

HTTP

GET https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Consumption/forecasts?$filter=properties/Grain eq 'Monthly'&api-version=2021-05-01

Sample response

Status code:: 200

{
  "value": [
    {
      "id": "/subscriptions/subid/providers/Microsoft.Consumption/forecasts/forecastId1",
      "name": "forecastId1",
      "type": "Microsoft.Consumption/forecasts",
      "properties": {
        "usageDate": "2018-04-01",
        "grain": "Monthly",
        "charge": 752,
        "currency": "USD",
        "chargeType": "Actual",
        "confidenceLevels": null
      }
    },
    {
      "id": "/subscriptions/subid/providers/Microsoft.Consumption/forecasts/forecastId2",
      "name": "forecastId2",
      "type": "Microsoft.Consumption/forecasts",
      "properties": {
        "usageDate": "2018-05-01",
        "grain": "Monthly",
        "charge": 753.809074,
        "currency": "USD",
        "chargeType": "Forecast",
        "confidenceLevels": [
          {
            "percentage": 95,
            "bound": "Upper",
            "value": 1165.951737
          },
          {
            "percentage": 95,
            "bound": "Lower",
            "value": 340.753404
          }
        ]
      }
    }
  ]
}

Definitions

Name	Description
Bound	The boundary of the percentage, values could be 'Upper' or 'Lower'
ChargeType	The type of the charge. Could be actual or forecast
ConfidenceLevels	The details about the forecast confidence levels. This is populated only when chargeType is Forecast.
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.
Forecast	A forecast resource.
ForecastsListResult	Result of listing forecasts. It contains a list of available forecasts.
Grain	The granularity of forecast. Please note that Yearly is not currently supported in this API. The API will provide responses in the Monthly grain if Yearly is selected. To get yearly grain data, please use our newer Forecast API.

Bound

Enumeration

The boundary of the percentage, values could be 'Upper' or 'Lower'

Value	Description
Upper
Lower

ChargeType

Enumeration

The type of the charge. Could be actual or forecast

Value	Description
Actual
Forecast

ConfidenceLevels

Object

The details about the forecast confidence levels. This is populated only when chargeType is Forecast.

Name	Type	Description
bound	Bound	The boundary of the percentage, values could be 'Upper' or 'Lower'
percentage	number (decimal)	The percentage level of the confidence
value	number (decimal)	The amount of forecast within the percentage level

ErrorDetails

Object

The details of the error.

Name	Type	Description
code	string	Error code.
message	string	Error message indicating why the operation failed.

ErrorResponse

Object

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.

Forecast

Object

A forecast resource.

Name	Type	Description
etag	string	The etag for the resource.
id	string	The full qualified ARM ID of an event.
name	string	The ID that uniquely identifies an event.
properties.charge	number (decimal)	The amount of charge
properties.chargeType	ChargeType	The type of the charge. Could be actual or forecast
properties.confidenceLevels	ConfidenceLevels[]	The details about the forecast confidence levels. This is populated only when chargeType is Forecast.
properties.currency	string	The ISO currency in which the meter is charged, for example, USD.
properties.grain	Grain	The granularity of forecast. Please note that Yearly is not currently supported in this API. The API will provide responses in the Monthly grain if Yearly is selected. To get yearly grain data, please use our newer Forecast API.
properties.usageDate	string	The usage date of the forecast.
tags	object	Resource tags.
type	string	Resource type.

ForecastsListResult

Object

Result of listing forecasts. It contains a list of available forecasts.

Name	Type	Description
value	Forecast[]	The list of forecasts.

Grain

Enumeration

The granularity of forecast. Please note that Yearly is not currently supported in this API. The API will provide responses in the Monthly grain if Yearly is selected. To get yearly grain data, please use our newer Forecast API.

Value	Description
Daily
Monthly
Yearly

Share via

Forecasts - List

URI Parameters

Responses

Security

azure_auth

Scopes

Examples

ForecastsList

Sample request

Sample response

ForecastsListFilterByDates

Sample request

Sample response

ForecastsListFilterByGrain

Sample request

Sample response

Definitions

Bound

ChargeType

ConfidenceLevels

ErrorDetails

ErrorResponse

Forecast

ForecastsListResult

Grain