Forecast - External Cloud Provider Usage

Service:: Cost Management

API Version:: 2025-03-01

Lists the forecast charges for external cloud provider type defined.

POST https://management.azure.com/providers/Microsoft.CostManagement/{externalCloudProviderType}/{externalCloudProviderId}/forecast?api-version=2025-03-01

With optional parameters:

POST https://management.azure.com/providers/Microsoft.CostManagement/{externalCloudProviderType}/{externalCloudProviderId}/forecast?api-version=2025-03-01&$filter={$filter}

URI Parameters

Name	In	Required	Type	Description
externalCloudProviderId	path	True	string	This can be '{externalSubscriptionId}' for linked account or '{externalBillingAccountId}' for consolidated account used with dimension/query operations.
externalCloudProviderType	path	True	ExternalCloudProviderType	The external cloud provider type associated with dimension/query operations. This includes 'externalSubscriptions' for linked account and 'externalBillingAccounts' for consolidated account.
api-version	query	True	string minLength: 1	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	ForecastDataset	Has definition for data in this forecast.
timeframe	True	ForecastTimeframe	The time frame for pulling data for the forecast. If custom, then a specific time period must be provided.
type	True	ForecastType	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		ForecastTimePeriod	Has time period for pulling data for the forecast.

Responses

Name	Type	Description
200 OK	ForecastResult	The request has succeeded.
Other Status Codes	ErrorResponse	An unexpected error response.

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

ExternalBillingAccountForecast

ExternalSubscriptionForecast

ExternalBillingAccountForecast

Sample request

HTTP

POST https://management.azure.com/providers/Microsoft.CostManagement/externalBillingAccounts/100/forecast?api-version=2025-03-01

{
  "type": "Usage",
  "dataset": {
    "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"
            ]
          }
        }
      ]
    },
    "granularity": "Daily"
  },
  "timePeriod": {
    "from": "2022-08-01T00:00:00+00:00",
    "to": "2022-08-31T23:59:59+00:00"
  },
  "timeframe": "Custom"
}

Sample response

Status code:: 200

{
  "name": "6dc7b06a-d90a-4df5-b655-ce6cf1c0814d",
  "type": "Microsoft.CostManagement/query",
  "id": "/providers/Microsoft.CostManagement/externalBillingAccounts/100/query/6dc7b06a-d90a-4df5-b655-ce6cf1c0814d",
  "properties": {
    "columns": [
      {
        "name": "PreTaxCost",
        "type": "Number"
      },
      {
        "name": "CostStatus",
        "type": "String"
      },
      {
        "name": "Currency",
        "type": "String"
      }
    ],
    "nextLink": null,
    "rows": [
      [
        0,
        "Forecast",
        "USD"
      ],
      [
        30.2572751438,
        "Forecast",
        "USD"
      ],
      [
        0.07675760200000002,
        "Forecast",
        "USD"
      ],
      [
        50.43096419040001,
        "Forecast",
        "USD"
      ]
    ]
  }
}

ExternalSubscriptionForecast

Sample request

HTTP

POST https://management.azure.com/providers/Microsoft.CostManagement/externalSubscriptions/100/forecast?api-version=2025-03-01

{
  "type": "Usage",
  "dataset": {
    "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"
            ]
          }
        }
      ]
    },
    "granularity": "Daily"
  },
  "timePeriod": {
    "from": "2022-08-01T00:00:00+00:00",
    "to": "2022-08-31T23:59:59+00:00"
  },
  "timeframe": "Custom"
}

Sample response

Status code:: 200

{
  "name": "d99477af-7510-40ee-aca2-e59bdca0d10d",
  "type": "Microsoft.CostManagement/query",
  "id": "/providers/Microsoft.CostManagement/externalSubscriptions/100/query/d99477af-7510-40ee-aca2-e59bdca0d10d",
  "properties": {
    "columns": [
      {
        "name": "PreTaxCost",
        "type": "Number"
      },
      {
        "name": "UsageDate",
        "type": "Number"
      },
      {
        "name": "CostStatus",
        "type": "String"
      },
      {
        "name": "Currency",
        "type": "String"
      }
    ],
    "nextLink": null,
    "rows": []
  }
}

Definitions

Name	Description
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. \n\nSome Error responses: \n\n * 429 TooManyRequests - Request is throttled. Retry after waiting for the time specified in the "x-ms-ratelimit-microsoft.consumption-retry-after" header. \n\n * 503 ServiceUnavailable - Service is temporarily unavailable. Retry after waiting for the time specified in the "Retry-After" header.
ExternalCloudProviderType
ForecastAggregation	The aggregation expression to be used in the forecast.
ForecastColumn	Forecast column properties
ForecastComparisonExpression	The comparison expression to be used in the forecast.
ForecastDataset	The definition of data present in the forecast.
ForecastDatasetConfiguration	The configuration of dataset in the forecast.
ForecastDefinition	The definition of a forecast.
ForecastFilter	The filter expression to be used in the export.
ForecastOperatorType	The operator to use for comparison.
ForecastResult	Result of forecast. It contains all columns listed under groupings and aggregation.
ForecastTimeframe	The time frame for pulling data for the forecast.
ForecastTimePeriod	Has time period for pulling data for the forecast.
ForecastType	The type of the forecast.
FunctionName	The name of the column to aggregate.
FunctionType	The name of the aggregation function to use.
GranularityType	The granularity of rows in the export. Currently 'Daily' is supported for most cases.

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. \n\nSome Error responses: \n\n * 429 TooManyRequests - Request is throttled. Retry after waiting for the time specified in the "x-ms-ratelimit-microsoft.consumption-retry-after" header. \n\n * 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.

ExternalCloudProviderType

Enumeration

Value	Description
externalSubscriptions
externalBillingAccounts

ForecastAggregation

Object

The aggregation expression to be used in the forecast.

Name	Type	Description
function	FunctionType	The name of the aggregation function to use.
name	FunctionName	The name of the column to aggregate.

ForecastColumn

Object

Forecast column properties

Name	Type	Description
name	string	The name of column.
type	string	The type of column.

ForecastComparisonExpression

Object

The comparison expression to be used in the forecast.

Name	Type	Description
name	string	The name of the column to use in comparison.
operator	ForecastOperatorType	The operator to use for comparison.
values	string[]	Array of values to use for comparison

ForecastDataset

Object

The definition of data present in the forecast.

Name	Type	Description
aggregation	<string, ForecastAggregation>	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	ForecastDatasetConfiguration	Has configuration information for the data in the export. The configuration will be ignored if aggregation and grouping are provided.
filter	ForecastFilter	Has filter expression to use in the forecast.
granularity	GranularityType	The granularity of rows in the forecast.

ForecastDatasetConfiguration

Object

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

Object

The definition of a forecast.

Name	Type	Description
dataset	ForecastDataset	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	ForecastTimePeriod	Has time period for pulling data for the forecast.
timeframe	ForecastTimeframe	The time frame for pulling data for the forecast. If custom, then a specific time period must be provided.
type	ForecastType	The type of the forecast.

ForecastFilter

Object

The filter expression to be used in the export.

Name	Type	Description
and	ForecastFilter[]	The logical "AND" expression. Must have at least 2 items.
dimensions	ForecastComparisonExpression	Has comparison expression for a dimension
or	ForecastFilter[]	The logical "OR" expression. Must have at least 2 items.
tags	ForecastComparisonExpression	Has comparison expression for a tag

ForecastOperatorType

Enumeration

The operator to use for comparison.

Value	Description
In

ForecastResult

Object

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	ForecastColumn[]	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

Enumeration

The time frame for pulling data for the forecast.

Value	Description
Custom

ForecastTimePeriod

Object

Has time period for pulling data for the forecast.

Name	Type	Description
from	string (date-time)	The start date to pull data from.
to	string (date-time)	The end date to pull data to.

ForecastType

Enumeration

The type of the forecast.

Value	Description
Usage
ActualCost
AmortizedCost

FunctionName

Enumeration

The name of the column to aggregate.

Value	Description
PreTaxCostUSD
Cost
CostUSD
PreTaxCost

FunctionType

Enumeration

The name of the aggregation function to use.

Value	Description
Sum

GranularityType

Enumeration

The granularity of rows in the export. Currently 'Daily' is supported for most cases.

Value	Description
Daily
Monthly