Forecast - External Cloud Provider Usage

Reference

Service:: Cost Management

API Version:: 2023-11-01

Lists the forecast charges for external cloud provider type defined.

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

With optional parameters:

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

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	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	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

ExternalBillingAccountForecast

ExternalSubscriptionForecast

ExternalBillingAccountForecast

Sample Request

HTTP

POST https://management.azure.com/providers/Microsoft.CostManagement/externalBillingAccounts/100/forecast?api-version=2023-11-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"
            ]
          }
        }
      ]
    }
  }
}

Sample Response

Status code:: 200

{
  "id": "providers/Microsoft.CostManagement/externalBillingAccounts/100/query/6dc7b06a-d90a-4df5-b655-ce6cf1c0814d",
  "name": "6dc7b06a-d90a-4df5-b655-ce6cf1c0814d",
  "type": "Microsoft.CostManagement/query",
  "properties": {
    "nextLink": null,
    "columns": [
      {
        "name": "PreTaxCost",
        "type": "Number"
      },
      {
        "name": "CostStatus",
        "type": "String"
      },
      {
        "name": "Currency",
        "type": "String"
      }
    ],
    "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=2023-11-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"
            ]
          }
        }
      ]
    }
  }
}

Sample Response

Status code:: 200

{
  "id": "providers/Microsoft.CostManagement/externalSubscriptions/100/query/d99477af-7510-40ee-aca2-e59bdca0d10d",
  "name": "d99477af-7510-40ee-aca2-e59bdca0d10d",
  "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": []
  }
}

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. 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.
externalCloudProviderType	The external cloud provider type associated with dimension/query operations. This includes 'externalSubscriptions' for linked account and 'externalBillingAccounts' for consolidated account.
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 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	ErrorDetails	The details of the error.

externalCloudProviderType

The external cloud provider type associated with dimension/query operations. This includes 'externalSubscriptions' for linked account and 'externalBillingAccounts' for consolidated account.

Name	Type	Description
externalBillingAccounts	string
externalSubscriptions	string

ForecastAggregation

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

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	ForecastOperatorType	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, 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

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	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

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

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	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

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

Forecast - External Cloud Provider Usage

URI Parameters

Request Body

Responses

Security

azure_auth

Scopes

Examples

ExternalBillingAccountForecast

Sample Request

Sample Response

ExternalSubscriptionForecast

Sample Request

Sample Response

Definitions

ErrorDetails

ErrorResponse

externalCloudProviderType

ForecastAggregation

ForecastColumn

ForecastComparisonExpression

ForecastDataset

ForecastDatasetConfiguration

ForecastDefinition

ForecastFilter

ForecastOperatorType

ForecastResult

ForecastTimeframe

ForecastTimePeriod

ForecastType

FunctionName

FunctionType

GranularityType

Additional resources