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

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.

204 No Content

No Content. Resource is not available.

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

BillingAccountForecast
BillingProfileForecast
DepartmentForecast
EnrollmentAccountForecast
InvoiceSectionForecast
ResourceGroupForecast
SubscriptionForecast

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

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.

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